Qt Labs StyleKit

StyleKit 是一个声明式样式系统， Qt Quick Controls，基于Qt Quick 模板构建。它允许您通过单个Style 对象为所有控件定义完整的视觉样式，包括对themes 、state-based 样式以及transitions 的支持。StyleKit会自动处理底层的模板实现，让您能够完全专注于视觉方面，例如colors 、尺寸、borders 以及shadows 。

StyleKit 的一个关键优势在于其分层属性系统：只需在基类（如abstractButton ）上设置一次属性，该属性就会自动应用于所有类似按钮的控件。如有需要，可针对特定控件或状态进行覆盖。样式更改会立即反映在所有控件上，在确保一致性的同时仍允许进行精细的自定义。

对于需要超出 StyleKit 提供范围的自定义行为的控件，您仍可实现自定义模板，并将其与采用 StyleKit 样式设置的控件无缝集成。

主要功能

声明式样式- 易于使用的 QML API，让您专注于设计而非实现
分层回退机制——所有属性均会传播。只需设置一次，并在需要时进行覆盖
基于状态的样式设置— 为悬停、按下、获得焦点等状态设计不同的外观
动画过渡——定义状态之间的平滑动画
主题支持——设计浅色和深色主题，以及任意数量的自定义主题
变体- 为同一控件设计多种变体
配色方案与字体集成——使用 QML 配置控件的配色方案和字体

以下示例展示了一个样式（Style）的最简示例：

// 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)
        }
    }
}

以下是在应用程序中设置样式的方法：

// Main.qml

import QtQuick
import Qt.labs.StyleKit

ApplicationWindow {
    id: app
    width: 1024
    height: 800
    visible: true

    // Assign the style to be used
    StyleKit.style: PlainStyle {}

    // Controls are used as normal
    Column {
        anchors.fill: parent
        anchors.margins: 10
        spacing: 10

        Button {
            text: "Button"
        }

        Slider {
            width: 200
        }
    }
}

在项目中使用该模块

可通过导入QtQuick.labs.StyleKit 来使用该模块的QML类型。要使用这些类型，请在您的.qml文件中添加以下导入语句：

import Qt.labs.StyleKit

文章与指南

StyleKit 功能概述——对可用样式功能的简要介绍
StyleKit 属性解析- StyleKit 如何解析样式属性值
参考备用样式

示例

StyleKit 快速控件示例——演示如何使用 Qt Quick Controls 。
StyleKit 控件示例——演示如何使用 StyleKit 设置样式 Qt Widgets 。
StyleKit 自定义委托示例——演示如何在StyleKit 中使用自定义委托和着色器效果。

C++ 类

QStyleKitStyle

将 Qt Labs StyleKit 样式应用到Qt Widgets

QML 类型

AbstractStyle	兼具“样式”和“主题”共性属性的抽象基类
BorderStyle	定义委托的边框样式
ControlStateStyle	描述控件在特定状态下的样式
ControlStyle	定义控件在正常状态下的样式
ControlStyleProperties	定义控件的可样式化属性
CustomControl	定义自定义（非内置）控件的样式
CustomTheme	定义一个命名的自定义主题
DelegateStyle	定义控件内某个元素的外观
HandleStyle	定义 Switch、Slider 和 RangeSlider 等控件的控点样式
ImageStyle	定义委托的图像样式
IndicatorStyle	定义控件指示器的样式
ShadowStyle	定义委托的投影样式
StylableControls	包含可设置样式的控件类型的抽象基类
Style	样式定义的根类型
StyleAnimation	用于对样式属性进行动画效果的便捷类型
StyleKit	用于设置和访问当前样式的单例
StyleKitDebug	追踪控件样式属性的解析过程
StyleReader	从特定控件的当前样式中读取属性
StyleVariation	为特定控件定义替代样式
StyledItem	渲染 DelegateStyle
SubIndicatorStyle	定义子指示器委托的样式
TextStyle	定义控件标签的文本样式
Theme	为配色方案定义颜色和样式覆盖规则

许可

Qt Labs StyleKit 可通过The Qt Company 获取商业许可。此外，它还遵循GNU 较宽松通用公共许可证第 3 版或 GNU 通用公共许可证第 2 版。更多详情请参阅Qt 许可条款。

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