自定义控件与 QSS
自绘控件与 QSS 美化,统一界面风格
#两条美化路线
做界面美化,Qt 给了两套机制,用错了会互相打架:
| 路线 | 手段 | 适合 |
|---|---|---|
| QSS(Qt Style Sheet) | 类似 CSS 的描述式语言 | 改颜色、边框、间距、状态反馈;不写 C++ 就能换肤 |
| 自绘控件 | 继承 QWidget 重写 paintEvent | 现有控件拼不出来的东西:仪表盘、波形图、流程图节点 |
正确的分工是:能用 QSS 解决的绝不自绘。QSS 一行能改的颜色,自绘要写十几行、还要处理禁用态、悬停态、不同 DPI。只有当需求超出标准控件的表达能力时,才动手写自绘控件,而且自绘控件内部仍应尽量通过 QStyle 绘制,以保持与平台观感一致。
#从零写一个自绘控件
一个规范的自定义控件至少要处理三件事:绘制、尺寸建议、状态反馈。下面实现一个"电池电量"控件:
// battery.h
#pragma once
#include <QWidget>
class Battery : public QWidget
{
Q_OBJECT
Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)
Q_PROPERTY(bool charging READ isCharging WRITE setCharging)
public:
explicit Battery(QWidget *parent = nullptr);
int value() const { return m_value; }
bool isCharging() const { return m_charging; }
QSize sizeHint() const override;
QSize minimumSizeHint() const override;
public slots:
void setValue(int v);
void setCharging(bool on);
signals:
void valueChanged(int value);
protected:
void paintEvent(QPaintEvent *event) override;
private:
int m_value = 60;
bool m_charging = false;
};Q_PROPERTY 不是装饰品。声明后,这个属性可以在 QSS 里被选择器匹配(Battery[charging="true"] { ... })、在 Qt Designer 属性编辑器里可见、还能被 动画框架 QPropertyAnimation 驱动。这是让自定义控件"融入 Qt 生态"的关键一步。
// battery.cpp
#include "battery.h"
#include <QPainter>
#include <QPaintEvent>
#include <QPolygonF>
#include <cmath>
Battery::Battery(QWidget *parent) : QWidget(parent)
{
setSizePolicy(QSizePolicy::Preferred, QSizePolicy::Fixed);
}
QSize Battery::sizeHint() const { return {80, 32}; }
QSize Battery::minimumSizeHint() const { return {40, 16}; }
void Battery::setValue(int v)
{
v = qBound(0, v, 100);
if (v == m_value) {
return; // 守卫:避免无谓重绘
}
m_value = v;
emit valueChanged(m_value);
update(); // 请求重绘,不是立即绘制
}
void Battery::setCharging(bool on)
{
if (on == m_charging) {
return;
}
m_charging = on;
update();
}
void Battery::paintEvent(QPaintEvent *)
{
QPainter p(this);
p.setRenderHint(QPainter::Antialiasing, true);
// 颜色随电量变化
QColor body = m_value > 50 ? QColor("#3ecf8e")
: (m_value > 20 ? QColor("#f5a623") : QColor("#e5484d"));
QRectF outline(1, 1, width() - 8, height() - 2); // 留出正极凸起
QRectF tip(outline.right() + 1, height() / 3.0, 5, height() / 3.0);
p.setPen(QPen(QColor("#5b6470"), 1.5));
p.setBrush(Qt::NoBrush);
p.drawRoundedRect(outline, 3, 3);
p.setBrush(QColor("#5b6470"));
p.drawRoundedRect(tip, 1, 1);
// 内部填充
const double margin = 3.0;
const double maxW = outline.width() - margin * 2;
const double w = maxW * m_value / 100.0;
p.setPen(Qt::NoPen);
p.setBrush(body);
p.drawRoundedRect(QRectF(outline.left() + margin, outline.top() + margin,
w, outline.height() - margin * 2), 2, 2);
if (m_charging) { // 充电时画一个闪电
p.setBrush(QColor(255, 255, 255, 220));
QPolygonF bolt;
QPointF c = outline.center();
bolt << QPointF(c.x() + 3, outline.top() + 4)
<< QPointF(c.x() - 4, c.y() + 2)
<< QPointF(c.x(), c.y() + 2)
<< QPointF(c.x() - 3, outline.bottom() - 4)
<< QPointF(c.x() + 5, c.y() - 2)
<< QPointF(c.x(), c.y() - 2);
p.drawPolygon(bolt);
}
}三个必须记住的约定:
- 构造
QPainter p(this),不要new。它必须在栈上,析构时自动end();忘了end()会导致绘制不完整。 - 用
update()而不是repaint()。update()只是"贴一张需要重绘的便签",Qt 会在下一个事件循环中合并多次请求;repaint()是立即同步绘制,滥用会拖垮性能。 sizeHint()/minimumSizeHint()决定布局中的默认尺寸。不重写它们,布局系统会给出一个莫名其妙的默认值。
#让属性动起来
声明了 Q_PROPERTY 后,几行代码就能做平滑动画:
#include <QPropertyAnimation>
void animateBattery(Battery *b)
{
auto *anim = new QPropertyAnimation(b, "value", b);
anim->setDuration(800);
anim->setStartValue(b->value());
anim->setEndValue(100);
anim->setEasingCurve(QEasingCurve::InOutQuad);
anim->start(QAbstractAnimation::DeleteWhenStopped);
}value 的 WRITE 函数内部调用 update(),动画框架每帧写入新值,控件就自动连续重绘。
#提升控件(Promote)
自绘控件写好了,怎么放进 .ui 文件?用提升(Promote)机制:
- 在 Designer 里拖一个
QWidget到窗体上; - 右键 → 提升为…;
- 填写"提升的类名称":
Battery,"头文件":battery.h; - 点击"添加",再点"提升"。
uic 生成的 ui_mainwindow.h 里会自动包含 battery.h,并把该对象声明为 Battery *。
| 项目 | 说明 |
|---|---|
| 基类选择 | 拖入的控件必须是你自定义类的基类(QWidget、QFrame 等) |
| 头文件路径 | 相对于 .ui 文件的路径,或已在 INCLUDEPATH 中的路径 |
| 全局包含 | 勾选后生成 #include <battery.h>,否则 #include "battery.h" |
提升的好处是:自定义控件可以像原生控件一样被布局管理、命名、在 Designer 里占位预览。如果需要在 Designer 里真正"看得见"渲染结果,那要写 Designer 插件(继承 QDesignerCustomWidgetInterface),工程量不小,一般项目不必做。
#QSS 语法
QSS 是 CSS 2.1 的一个子集,且只作用于 QWidget 及其子类。基本结构是 选择器 { 属性: 值; }。
#选择器
| 选择器 | 示例 | 含义 |
|---|---|---|
| 类型 | QPushButton { } | 所有 QPushButton 实例 |
| ID | QPushButton#okBtn { } | objectName 为 okBtn 的按钮 |
| 属性 | QPushButton[flat="false"] { } | 属性值匹配 |
| 后代 | QDialog QPushButton { } | Dialog 内所有层级的按钮 |
| 子代 | QDialog > QPushButton { } | 仅直接子对象 |
| 通配 | * { } | 所有控件 |
#盒模型与常用属性
QSS 的盒模型与 CSS 一致:margin → border → padding → content。绘制背景时最关键的是 background-clip——它决定背景绘制到哪一层。
/* 通用按钮:扁平风格 —— 保存为 style.qss */
QPushButton {
background-color: #2d7ff9;
color: #ffffff;
border: none;
border-radius: 4px;
padding: 6px 16px;
min-width: 64px;
font: 14px "Microsoft YaHei";
}
/* 伪状态:顺序很重要,后面的覆盖前面的 */
QPushButton:hover { background-color: #4291ff; }
QPushButton:pressed { background-color: #1c6ae0; padding-top: 7px; padding-bottom: 5px; }
QPushButton:disabled { background-color: #c9cdd4; color: #8a9099; }
QPushButton:checked { background-color: #1c6ae0; border: 2px solid #90c2ff; }
QPushButton:focus { outline: none; border: 2px solid #90c2ff; }
/* 子控件:下拉箭头 */
QComboBox::drop-down {
subcontrol-origin: padding;
subcontrol-position: right center;
width: 20px;
border-left: 1px solid #d0d5dd;
}
QComboBox::down-arrow { image: url(:/icons/arrow-down.svg); }
QComboBox QAbstractItemView {
selection-background-color: #e8f1ff;
selection-color: #1a1a1a;
}
/* 滚动条 */
QScrollBar:vertical {
background: #f2f4f7;
width: 10px;
margin: 0;
}
QScrollBar::handle:vertical {
background: #c4c9d1;
border-radius: 5px;
min-height: 24px;
}
QScrollBar::handle:vertical:hover { background: #a6acb8; }
QScrollBar::add-line:vertical, QScrollBar::sub-line:vertical { height: 0; }这段 QSS 里藏着几个实战经验:
:pressed时微调padding制造"按下去"的位移感,这是纯 CSS 做不到而 QSS 可以的小技巧。QComboBox QAbstractItemView是后代选择器,用来改下拉列表样式——直接写QComboBox::item在新版本 Qt 中不一定生效,改子窗口部件才是可靠做法。- 滚动条必须同时设置
::handle和:vertical,并把add-line/sub-line高度设为 0,否则会出现难看的箭头按钮。
#伪状态的优先级
QSS 遵循"更具体的规则胜出",而伪状态让规则更具体。因此书写顺序应为:基础 → hover → pressed → disabled。若把 QPushButton:disabled 写在最前面,禁用态会被后面的通用规则覆盖,控件看起来仍可点击——这是非常常见的 bug。
#QSS 与 QPalette 的关系
这是最容易混淆的地方。两者都能改颜色,但作用层次不同:
| 机制 | 作用层 | 影响范围 | 典型用途 |
|---|---|---|---|
| QPalette | 底层,向 QStyle 提供配色 | 所有控件(含自绘中调用 QStyle 的部分) | 全局深色模式 |
| QSS | 上层,覆盖 QStyle 的绘制结果 | 只影响匹配到的控件 | 局部定制、换肤 |
关键规则:一旦给某个控件设置了 QSS,Qt 会用一个特殊的 QStyleSheetStyle 代理它,此时该控件的 QPalette 大部分失效。这就是"我改了 palette 却没效果"的根源——祖先控件上挂了 QSS,导致整棵子树的 palette 被架空。
实践建议:
- 要做深色模式,用
QApplication::setPalette()配合QApplication::setStyle("Fusion")。Fusion 是唯一能被 palette 完整驱动的跨平台风格。 - 要做局部定制(比如一个特殊样式的按钮),用 QSS。
- 两者混用时,QSS 所在子树内不要再依赖 palette,颜色直接写进 QSS。
#include <QApplication>
#include <QFile>
#include <QPalette>
#include <QStyleFactory>
#include <QDebug>
static QPalette darkPalette()
{
QPalette p;
p.setColor(QPalette::Window, QColor(0x1e, 0x20, 0x24));
p.setColor(QPalette::WindowText, Qt::white);
p.setColor(QPalette::Base, QColor(0x28, 0x2b, 0x30));
p.setColor(QPalette::AlternateBase, QColor(0x32, 0x35, 0x3b));
p.setColor(QPalette::Text, Qt::white);
p.setColor(QPalette::Button, QColor(0x35, 0x38, 0x3e));
p.setColor(QPalette::ButtonText, Qt::white);
p.setColor(QPalette::Highlight, QColor(0x2d, 0x7f, 0xf9));
p.setColor(QPalette::HighlightedText, Qt::white);
p.setColor(QPalette::Disabled, QPalette::Text, QColor(0x70, 0x74, 0x7a));
return p;
}
void applyTheme(QApplication &app, bool dark, const QString &qssPath)
{
if (dark) {
app.setStyle(QStyleFactory::create("Fusion"));
app.setPalette(darkPalette());
}
QFile f(qssPath);
if (f.open(QIODevice::ReadOnly | QIODevice::Text)) {
app.setStyleSheet(QString::fromUtf8(f.readAll())); // 全局 QSS
} else {
qWarning() << "QSS 加载失败:" << qssPath;
}
}注意 setStyleSheet() 的继承性:设在 QApplication 上作用于所有控件,设在某个 QWidget 上则作用于它及其子孙。大型界面可把 QSS 拆成"全局基础 + 各模块增量",但要记住后设置的内容是完全替换而非追加。
#Designer 与手写代码怎么选
| 场景 | 推荐 | 理由 |
|---|---|---|
| 静态布局、界面元素多 | Designer(.ui) | 所见即所得,调整布局不需重编译逻辑 |
| 动态生成控件(列表项、配置项) | 手写代码 | 数量在编译期未知 |
| 需要精细调整尺寸策略 | Designer | 各种 sizePolicy 组合试起来快 |
| 复杂自绘控件 | 手写 + 提升占位 | Designer 无法预览自绘结果 |
| 团队中有非程序员参与 | Designer | 降低协作门槛 |
成熟的折中方案是:主窗口骨架用 .ui,动态区域用手写代码填充。比如主窗口的菜单、工具栏、状态栏、分割器在 Designer 里搭好,中间内容区留一个空的 QVBoxLayout,运行时按数据动态往里塞控件。既享受 Designer 的效率,又保留灵活性。
Qt 5 提示:
app.setStyleSheet()的行为在 Qt 6 与 Qt 5 中一致。差异在于 Qt 6 精简了内置风格,QStyleFactory::keys()返回的可用风格更少(Windows Vista 风格已移除);基于 palette 的深色模式在两代中都应搭配 Fusion 使用。
#小结
- 美化优先用 QSS,标准控件无法表达时才自绘;自绘控件内部应尽量调用
QStyle以保持原生观感。 - 自定义控件三要素:
paintEvent()绘制、sizeHint()给尺寸建议、Q_PROPERTY接入属性系统与动画框架。 - 刷新用
update()(异步合并)而非repaint()(同步立即);QPainter必须在栈上构造。 - QSS 选择器支持类型、ID、属性、后代与子控件(
::);伪状态的书写顺序决定优先级。 - QSS 会用
QStyleSheetStyle代理控件,使该子树的QPalette基本失效——全局主题用 Palette + Fusion,局部定制用 QSS。
#练习
- 给
Battery加一个warningThreshold属性,低于阈值时电量条闪烁(提示:QTimer+update())。 - 用「提升」机制把
Battery放进一个.ui文件,并在 Designer 属性编辑器中直接设置value。 - 写一份全局 QSS,统一
QPushButton、QLineEdit、QTableView、QScrollBar的样式,实现浅色/深色两套主题并支持运行时热切换。 - 实现一个自绘的"圆形进度环"控件,支持
value、lineWidth、startAngle三个属性,并用QPropertyAnimation做入场动画。