Back to Qt.io
Contact Us Blog Download Qt
本页内容

Style QML Type

样式定义的根类型。更多...

Import Statement: import Qt.labs.StyleKit
Inherits:

AbstractStyle

Status: Technology preview

此类型处于技术预览阶段，可能会有变动。

属性

详细说明

Style 是 StyleKit 中用于为 Qt Quick Controls。样式可用于自定义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
            width: 100
            height: 36
        }
        indicator {
            width: 20
            height: 20
            border.width: 1
        }
        handle {
            width: 20
            height: 20
            radius: 10
        }
    }

    button {
        background {
            width: 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.fillWidth: true
        indicator.height: 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 以及StyleKit 属性解析。

属性文档

availableThemeNames : list<string> [read-only]

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

另请参阅 themeName 和customThemeNames 。

customThemeNames : list<string> [read-only]

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

另请参阅 availableThemeNames 、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]

当前活动的主题实例。它根据themeName 的设置，从light theme component 、dark theme component 或custom themes 中的某个主题实例化而来。

在解析样式属性时，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.availableThemeNames
    onCurrentTextChanged: StyleKit.style.themeName = currentText
}

支持的值：

注意：主题 仅在定义它们的Style 内有效，且只能作为该样式的当前主题进行设置。要使当前主题生效，该样式所属的样式必须也是应用程序中的current style 。

另请参阅 availableThemeNames 和theme 。

© 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.