编写支持样式的小部件
支持样式的控件会遵循其绘制所采用的样式。它不会自行绘制边框、按钮和指示器,而是请求当前样式来绘制这些元素,并向样式获取布局内容所需的度量数据。 这样,该控件在每个平台上都能呈现原生外观,遵循应用程序的配色方案,并能像 Qt Widgets 自带的控件一样采用自定义样式或样式表。
构建样式选项
样式会从QStyleOption 中的信息进行渲染,因此绘制事件中的第一步就是填充该对象。选择与要绘制的元素匹配的选项类,调用QStyleOption::initFrom() 来设置所有控件共有的状态标志、矩形、配色方案和字体度量,然后设置该元素特有的成员。
Qt Widgets 的控件通过initStyleOption() 中的受保护虚拟函数实现这一点,以便子类能够调整该选项。在您的控件中也请遵循相同的模式。
通过样式进行绘制
使用 `QStyle` 的绘制函数绘制元素,并传入选项、一个 `QPainter` 以及小部件本身:
QPainter painter(this);
...
style()->drawPrimitive(QStyle::PE_FrameFocusRect, &option, &painter, this);QStylePainter 该组件结合了 `QStyle`、`QPainter` 和 `QWidget`。其绘制函数仅接受元素和选项作为参数,从而使代码更简洁:
QStylePainter painter(this);
...
painter.drawPrimitive(QStyle::PE_FrameFocusRect, option);
在选项中使用调色板,或使用QWidget::palette() 来指定任何自定义颜色,这样控件就能遵循应用程序的调色板,并在浅色和深色主题下均能正常工作。
从样式中获取尺寸
请基于样式调用 `sizeHint()` 和 `minimumSizeHint()`。`sizeFromContents()` 会根据给定的内容类型,将内容尺寸转换为控件尺寸;而 `pixelMetric()` 则返回样式中框架的宽度、边距和指示器尺寸。请使用 `subElementRect()` 来获取样式中元素各部分的位置,而非自行计算位置。
报告小部件的状态
只有当状态标志被设置时,样式才会绘制悬停和焦点效果。在控件上设置WA_Hover 属性以接收悬停事件,并在鼠标悬停在元素上时将State_MouseOver 添加到该选项中。在控件被按下时设置State_Sunken ,对于可选中元素,则设置State_On 、State_Off 或State_NoChange 。《控件样式参考》列出了每个元素所期望的标志。
跟踪样式和调色板的变更
当应用程序样式或配色方案发生变化时,控件会在 `changeEvent()` 中收到 `QEvent::StyleChange ` 或 `QEvent::PaletteChange ` 事件。若您的尺寸提示取决于样式,请在此处清空任何缓存的度量值,并调用 `updateGeometry()`。
支持从右到左的布局
在从右到左的布局中,样式会镜像非对称元素。请使用visualRect() 将矩形从逻辑坐标转换为屏幕坐标,并使用visualAlignment() 镜像对齐方式,同时将选项的direction 传递给样式。请使用-reverse 命令行选项进行测试。
另请参阅 QStyle 、QStylePainter 、QStyleOption 、《样式如何绘制控件》以及《控件样式参考》。
© 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.