Back to Qt.io
Contact Us Blog Download Qt
在本页

Style QML Type

样式定义的根类型。更多

Import Statement: import Qt.labs.StyleKit
Inherits:

AbstractStyle

属性

详细说明

Style 是StyleKit 中的根类型，用于为Qt Quick 控件定义完整的可视化样式。通过样式，您可以自定义every control type -backgrounds,indicators,handles,text,padding 等的外观，以及控件对hovered,pressed 和disabled 等状态的响应方式，包括它们之间的动画transitions 。

通过themes ，样式支持light 和dark 颜色方案，您还可以添加任意数量的custom themes 。Style variations 允许您定义可应用于特定控件实例或整个控件类型的替代样式。您还可以定义custom controls ，将样式扩展到内置控件集之外。

下面的示例显示了一种最小样式，它定义了所有主题共享的一些结构属性，并为颜色分别定义了浅色和深色主题：

// PlainStyle.qml

import QtQuick
import Qt.labs.StyleKit

Style {
    control {
        padding: 6
        background {
            radius: 4
            implicitWidth: 100
            implicitHeight: 36
        }
        indicator {
            implicitWidth: 20
            implicitHeight: 20
            border.width: 1
        }
        handle {
            implicitWidth: 20
            implicitHeight: 20
            radius: 10
        }
    }

    button {
        background {
            implicitWidth: 120
            shadow.opacity: 0.6
            shadow.verticalOffset: 2
            shadow.horizontalOffset: 2
            gradient: Gradient {
                GradientStop { position: 0.0; color: Qt.alpha("black", 0.0)}
                GradientStop { position: 1.0; color: Qt.alpha("black", 0.2)}
            }
        }
        pressed.background.scale: 0.95
    }

    slider {
        indicator.implicitWidth: Style.Stretch
        indicator.implicitHeight: 6
        indicator.radius: 3
    }

    light: Theme {
        applicationWindow {
            background.color: "whitesmoke"
        }
        control {
            text.color: "black"
            background.color: "#e8e8e8"
            background.border.color: "#c0c0c0"
            hovered.background.color: "#d0d0d0"
        }
        button {
            text.color: "white"
            background.color: "cornflowerblue"
            background.shadow.color: "gray"
            hovered.background.color: "royalblue"
        }
    }

    dark: Theme {
        applicationWindow {
            background.color: Qt.darker("gray", 2.0)
        }
        control {
            text.color: "white"
            background.color: "#3a3a3a"
            background.border.color: "#555555"
            hovered.background.color: "#4a4a4a"
        }
        button {
            background.color: "sandybrown"
            background.shadow.color: "black"
            hovered.background.color: Qt.darker("sandybrown", 1.2)
        }
    }
}

有关更完整的示例，请参阅StyleKit 示例。

注意： Qt.labs 模块中的类型不保证在未来版本中保持兼容。

另请参阅 Theme,CustomTheme,StyleVariation,ControlStyle,DelegateStyle,CustomControl, 以及属性解析。

属性文档

Stretch : int [read-only]

一个哨兵值，当分配给委托的implicitWidth 或implicitHeight 时，会使委托填满沿该轴的可用空间。可用空间将受布局属性（如margins 和padding ）的限制。

例如，要使滑块槽填满可用宽度：

slider {
    indicator.implicitWidth: Style.Stretch
    indicator.implicitHeight: 6
}

另请参阅 DelegateStyle::implicitWidth 和DelegateStyle::implicitHeight 。

customThemeNames : list<string> [read-only]

样式中定义的所有custom themes 的名称。这不包括built-in themes.

另请参见 themeNames,themeName, 和CustomTheme 。

dark : Component

暗色主题组件。当系统处于暗色模式且themeName 为"System" ，或themeName 被明确设置为"Dark" 时，它将被实例化并应用。

dark: Theme {
    control.background.color: "#404040"
    button.hovered.background.color: "#6ab0f9"
}

另请参阅 light,themeName, 和主题。

fallbackStyle : Style

用于解决未在此样式中明确设置的属性的后备样式。如果在样式或其活动主题中找不到某个属性，StyleKit 将在后备样式中查找该属性。

默认情况下，后备样式被设置为内部样式，提供与Basic样式类似的基本外观。

您可以将其设置为自定义样式，或设置为null 以完全禁用回退解析。请注意，将其设置为null 意味着完全从零开始，这就需要设置比其他需要更多的属性。回退样式的参考实现可在此处找到。

另请参阅 "属性解析"。

light : Component

灯光主题组件。当系统处于轻量模式且themeName 为"System" 时，或themeName 被明确设置为"Light" 时，它将被实例化并应用。

light: Theme {
    control.background.color: "#f0f0f0"
    button.hovered.background.color: "#4a90d9"
}

另请参阅 dark,themeName, 和主题。

palette : palette [read-only]

样式控件的调色板。

使用该调色板可将样式中的颜色与被样式化控件的palette 绑定。如果应用程序为控件指定了不同的调色板，样式将发生变化，控件将重新绘制。

button.background.color: palette.accent
button.text.color: palette.buttonText

另请参见 StyleReader::palette 。

theme : Theme [read-only]

当前活动的主题实例。它从light theme component 、dark theme component 或custom themes 中的一个实例化，具体取决于themeName 。

在解析样式属性时，StyleKit 会首先在该主题中查找该属性（StyleVariations 放在一边）。如果未找到该属性，它会返回到Style 中查找。

另请参见 themeName,light, 和dark 。

themeName : string

当前活动主题的名称。默认值为"System" ，它会根据QStyleHints::colorScheme 报告的配色方案自动选择light 或dark 。

您可以通过设置此属性来更改此样式的当前主题。

// Main.qml

StyleKit.style: YourStyleKitStyle {
    // Set a theme different from "System" at start-up
    themeName: "Dark"
}

ComboBox {
    // Let the user select a different theme at run-time
    model: StyleKit.style.themeNames
    onCurrentTextChanged: StyleKit.style.themeName = currentText
}

支持的值

注意： 主题是Style 的本地主题，只能将其设置为该样式的当前主题。要使当前主题生效，它所属的样式也必须是应用程序中的current style 。

另请参阅 themeNames 和theme 。

themeNames : list<string> [read-only]

所有可用主题的名称，包括"System","Light","Dark", 以及任意主题。custom themes.

另请参阅 themeName 和customThemeNames 。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.