QStyleKitStyle Class
QStyleKitStyle 类将Qt Labs StyleKit样式应用于 `Qt Widgets`。更多内容...
| 头文件: | #include <QStyleKitStyle> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS LabsStyleKit) target_link_libraries(mytarget PRIVATE Qt6::LabsStyleKit) |
| 自: | Qt 6.12 |
| 继承自: | QCommonStyle |
属性
- availableThemeNames : QStringList
- customThemeNames : QStringList
- stylePath : QString
- themeName : QString
公共函数
| QStyleKitStyle() | |
| QStyleKitStyle(const QString &filePath) | |
| virtual | ~QStyleKitStyle() override |
| QStringList | availableThemeNames() const |
| QStringList | customThemeNames() const |
| void | setStylePath(const QString &filePath) |
| void | setThemeName(const QString &themeName) |
| QString | stylePath() const |
| QString | themeName() const |
重新实现的公共函数
| virtual void | drawComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *w = nullptr) const override |
| virtual void | drawControl(QStyle::ControlElement element, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const override |
| virtual void | drawPrimitive(QStyle::PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const override |
| virtual QStyle::SubControl | hitTestComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *w = nullptr) const override |
| virtual int | pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt = nullptr, const QWidget *widget = nullptr) const override |
| virtual void | polish(QApplication *app) override |
| virtual void | polish(QPalette &palette) override |
| virtual void | polish(QWidget *widget) override |
| virtual QSize | sizeFromContents(QStyle::ContentsType ct, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget = nullptr) const override |
| virtual QPalette | standardPalette() const override |
| virtual int | styleHint(QStyle::StyleHint sh, const QStyleOption *opt = nullptr, const QWidget *w = nullptr, QStyleHintReturn *shret = nullptr) const override |
| virtual QRect | subControlRect(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QStyle::SubControl sc, const QWidget *w = nullptr) const override |
| virtual QRect | subElementRect(QStyle::SubElement r, const QStyleOption *opt, const QWidget *widget = nullptr) const override |
| virtual void | unpolish(QApplication *app) override |
| virtual void | unpolish(QWidget *widget) override |
信号
| void | availableThemeNamesChanged(const QStringList &availableThemeNames) |
| void | customThemeNamesChanged(const QStringList &customThemeNames) |
| void | stylePathChanged(const QString &stylePath) |
| void | themeNameChanged(const QString &themeName) |
重新实现的受保护函数
| virtual bool | event(QEvent *event) override |
| virtual bool | eventFilter(QObject *obj, QEvent *event) override |
详细说明
QStyleKitStyle 是一种QStyle 实现,它使用StyleKit Style 来为Qt Widgets 设置样式。Style 是一个QML文件,它以声明式方式描述了每种控件类型及其状态的视觉设计(颜色、尺寸、半径、边框及其他属性)。这些属性值驱动绘制过程,该过程完全通过QPainter 实现。Qt Quick 和场景图在渲染过程中不发挥任何作用。
这种分离意味着同一个Style QML 文件既可以驱动Qt Quick Controls ,也可以驱动Qt Widgets ,从而在两个系统中共享一个设计定义。
注意:StyleKit 是 Qt Labs 模块,其 API 可能会在不同的 Qt 版本之间发生变化。
加载样式
样式是一个 QML 文件,其根对象为Style 。要加载它,请将文件路径传递给构造函数或setStylePath():
auto *style = new QStyleKitStyle(QStringLiteral(":/styles/MyStyle.qml"));
QApplication::setStyle(style);样式将通过由 QStyleKitStyle 实例拥有的内部QQmlEngine 进行加载。如果路径无效或根对象不是Style ,则会发出警告,并且该样式将使用默认的备用样式,直到设置了有效的stylePath 为止。
主题
一个样式可以定义一个或多个命名的themes 。通过setThemeName()选择活动主题;可用主题列表通过availableThemeNames 暴露。特殊主题名称System 会使样式遵循平台配色方案:当操作系统配色方案发生变化时,活动主题会自动重建,所有小部件都会重新渲染。
控件与 StyleKit 控件的映射
每个Qt Widgets 类都映射到一个 StyleKit 控件类型,这决定了Style 中哪个控件条目适用于它。 使用相应的控件条目来配置该小部件类型的视觉属性,包括小部件的各个部分,例如其背景、指示器、手柄等。有关可样式化属性的完整列表,请参阅ControlStyleProperties 。未在特定控件条目中设置的属性将通过控件类型层次结构进行回退:例如,button 将回退到abstractButton ,而后者又将回退到control 。
上述未列出的控件目前尚不被 QStyleKitStyle 支持,将由QCommonStyle 负责绘制。其余控件的支持计划在未来版本中实现。反之,StylableControls 中的一些控件条目在Qt Widgets 中没有对应项,因此在为控件设置样式时不会被应用。
控件内的子控件
控件内的各个子控件可以单独进行样式设置,因为每个子控件都映射到Style 中的一个独立控件条目:
| 子元素 | StyleKit 控件 |
|---|---|
| QStyledItemDelegate items——所有 Qt 项视图的默认委托,包括QComboBox 弹出列表 | itemDelegate |
| 当这些项目可由用户勾选(即显示勾选标记)时 | checkDelegate;对于未显式设置的任何内容,将回退到itemDelegate |
| 中的各个选项卡QTabBar | tabButton |
| QMenu items | menuItem |
| 中的分隔符QMenu | menuSeparator |
| QMenuBar 项目 | menuBarItem |
| 中的分隔符QToolBar | toolSeparator |
| QComboBox 下拉列表容器 | popup |
已知限制
QStyleKitStyle 处于技术预览阶段。当前,Qt Widgets 不支持以下 StyleKit 功能:
- 阴影— 阴影不会被渲染。
- 控件背景的委托缩放比例大于1.0时——小部件无法在其自身矩形范围外绘制,因此缩放后的背景会在小部件边缘被裁剪。请使用margins 将背景内缩,并为其预留扩展空间。缩放指示器、控制柄和前景不受影响。
- 变体— 目前尚不支持在小部件实例上设置 `StyleVariation `。
- 自定义控件— 目前尚不支持使用 `CustomControl ` 对自定义控件进行样式设置。
- 自定义委托— 不使用 `delegate ` 属性;始终应用内置的渲染方式。
计划在未来版本中支持这些功能。
另请参阅 QStyle 、QCommonStyle 、Qt Labs StyleKit、Style 以及Theme 。
属性文档
[read-only] availableThemeNames : QStringList
该属性包含已加载的Style 所暴露的主题名称列表。
该列表包含内置的Light 和Dark 主题,以及由该样式定义的任何自定义主题。
访问函数:
| QStringList | availableThemeNames() const |
通知信号:
| void | availableThemeNamesChanged(const QStringList &availableThemeNames) |
[read-only] customThemeNames : QStringList
该属性保存了由已加载的Style 定义的自定义主题名称列表。
与availableThemeNames 不同,该列表不包含内置的Light 和Dark 主题,仅包含样式作者显式定义的主题。若未加载任何样式,则返回空列表。
访问函数:
| QStringList | customThemeNames() const |
通知信号:
| void | customThemeNamesChanged(const QStringList &customThemeNames) |
另请参阅 availableThemeNames 和themeName 。
stylePath : QString
该属性存储了驱动此样式的 QML 文件(Style )的路径。
该值可以是本地文件的路径,也可以是资源文件系统中文件的路径(例如,:/styles/MyStyle.qml )。 相对路径将以应用程序的工作目录为基准进行解析。该文件必须包含一个 QML 组件,且其根对象为 `Style`。设置此属性会重新加载样式;如果无法加载新文件,则保留先前加载的样式并发出警告。
访问函数:
| QString | stylePath() const |
| void | setStylePath(const QString &filePath) |
Notifier 信号:
| void | stylePathChanged(const QString &stylePath) |
themeName : QString
该属性存储活动主题的名称。
该值必须是availableThemeNames 中列出的选项之一,或特殊名称System ,以遵循平台配色方案。设置此属性将更新所有小部件,使其根据新主题重新绘制。
访问函数:
| QString | themeName() const |
| void | setThemeName(const QString &themeName) |
通知器信号:
| void | themeNameChanged(const QString &themeName) |
成员函数文档
QStyleKitStyle::QStyleKitStyle()
构建一个未加载任何样式的 QStyleKitStyle。
在构造完成后,使用 `setStylePath()` 加载 QML 样式Style 。在加载样式之前,该样式将使用默认的备用样式。
[explicit] QStyleKitStyle::QStyleKitStyle(const QString &filePath)
创建一个 QStyleKitStyle 对象,并加载位于filePath 的 QML 文件Style 。
filePath 是本地文件的路径或资源文件系统中文件的路径;相对路径将以应用程序的工作目录为基准进行解析。如果路径无效,或者加载的组件的根对象不是Style ,则会发出警告,且生成的样式将使用默认的备用样式,直到设置了有效的stylePath 为止。
[override virtual noexcept] QStyleKitStyle::~QStyleKitStyle()
销毁QStyleKitStyle 。
QStringList QStyleKitStyle::availableThemeNames() const
返回已加载的Style 所提供的所有主题名称,包括内置的Light 和Dark 主题,以及该样式定义的任何自定义主题。若未加载任何样式,则返回一个空列表。
注意: 这是属性 availableThemeNames 的获取 函数。
另请参阅 customThemeNames() 和themeName()。
QStringList QStyleKitStyle::customThemeNames() const
返回由已加载的Style 定义的自定义主题名称,不包括内置的Light 和Dark 主题。若未加载任何样式,则返回一个空列表。
注意: 这是 customThemeNames 属性的获取函数 。
另请参阅 availableThemeNames()。
[override virtual] void QStyleKitStyle::drawComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *w = nullptr) const
重写了:QCommonStyle::drawComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *widget) const。
[override virtual] void QStyleKitStyle::drawControl(QStyle::ControlElement element, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const
重写了:QCommonStyle::drawControl(QStyle::ControlElement element, const QStyleOption *opt, QPainter *p, const QWidget *widget) const。
[override virtual] void QStyleKitStyle::drawPrimitive(QStyle::PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w = nullptr) const
重写了:QCommonStyle::drawPrimitive(QStyle::PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *widget) const。
[override virtual protected] bool QStyleKitStyle::event(QEvent *event)
重写了:QObject::event(QEvent *e)。
[override virtual protected] bool QStyleKitStyle::eventFilter(QObject *obj, QEvent *event)
重写了:QObject::eventFilter(QObject *watched, QEvent *event)。
[override virtual] QStyle::SubControl QStyleKitStyle::hitTestComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *w = nullptr) const
重写了:QCommonStyle::hitTestComplexControl(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *widget) const。
[override virtual] int QStyleKitStyle::pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt = nullptr, const QWidget *widget = nullptr) const
重写了:QCommonStyle::pixelMetric(QStyle::PixelMetric m, const QStyleOption *opt, const QWidget *widget) const。
[override virtual] void QStyleKitStyle::polish(QApplication *app)
重写了:QCommonStyle::polish(QApplication *app)。
[override virtual] void QStyleKitStyle::polish(QPalette &palette)
重写了:QCommonStyle::polish (QPalette &pal)。
[override virtual] void QStyleKitStyle::polish(QWidget *widget)
重写了:QCommonStyle::polish(QWidget *widget)。
void QStyleKitStyle::setStylePath(const QString &filePath)
加载位于filePath 的 QMLStyle ,并将其应用于所有控件。
filePath 是本地文件的路径,或是资源文件系统中文件的路径;有关允许的格式,请参阅stylePath 属性。如果该路径与当前的stylePath 相同,则此函数不执行任何操作。如果无法加载新样式,则先前加载的样式仍保持有效,并会触发一条警告;同时仍会触发stylePathChanged() 事件,以反映属性值的变化。
注意: 这是属性stylePath 的设置 函数。
另请参阅 stylePath()。
void QStyleKitStyle::setThemeName(const QString &themeName)
激活名为themeName 的主题。
themeName 该值必须是availableThemeNames()中的一个条目,或是特殊名称System ,以遵循平台的配色方案。如果未加载任何Style ,该函数将发出警告并返回,同时不更改当前主题。
注意: 这是属性themeName 的设置 函数。
另请参阅 themeName() 和availableThemeNames()。
[override virtual] QSize QStyleKitStyle::sizeFromContents(QStyle::ContentsType ct, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget = nullptr) const
重写了:QCommonStyle::sizeFromContents(QStyle::ContentsType contentsType, const QStyleOption *opt, const QSize &contentsSize, const QWidget *widget) const。
[override virtual] QPalette QStyleKitStyle::standardPalette() const
重新实现了:QStyle::standardPalette() const。
[override virtual] int QStyleKitStyle::styleHint(QStyle::StyleHint sh, const QStyleOption *opt = nullptr, const QWidget *w = nullptr, QStyleHintReturn *shret = nullptr) const
重写了:QCommonStyle::styleHint(QStyle::StyleHint sh, const QStyleOption *opt, const QWidget *widget, QStyleHintReturn *hret) const。
QString QStyleKitStyle::stylePath() const
返回当前加载的Style 文件的路径。
注意: 这是 stylePath 属性的获取器 函数。
另请参阅 setStylePath()。
[override virtual] QRect QStyleKitStyle::subControlRect(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QStyle::SubControl sc, const QWidget *w = nullptr) const
重写了:QCommonStyle::subControlRect(QStyle::ComplexControl cc, const QStyleOptionComplex *opt, QStyle::SubControl sc, const QWidget *widget) const。
[override virtual] QRect QStyleKitStyle::subElementRect(QStyle::SubElement r, const QStyleOption *opt, const QWidget *widget = nullptr) const
重写了:QCommonStyle::subElementRect(QStyle::SubElement sr, const QStyleOption *opt, const QWidget *widget) const。
QString QStyleKitStyle::themeName() const
返回当前活动的主题名称;如果未加载任何Style ,则返回空字符串。
注意: 这是 themeName 属性的获取函数 。
另请参阅 setThemeName() 和availableThemeNames()。
[override virtual] void QStyleKitStyle::unpolish(QApplication *app)
重写了:QCommonStyle::unpolish(QApplication *application)。
[override virtual] void QStyleKitStyle::unpolish(QWidget *widget)
重写了:QCommonStyle::unpolish(QWidget *widget)。
© 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.