QC++ / Qt 学习之路

自定义控件与 QSS

自绘控件与 QSS 美化,统一界面风格

进阶第 28 / 48 章第四篇 · Qt 进阶

#两条美化路线

做界面美化,Qt 给了两套机制,用错了会互相打架:

路线手段适合
QSS(Qt Style Sheet)类似 CSS 的描述式语言改颜色、边框、间距、状态反馈;不写 C++ 就能换肤
自绘控件继承 QWidget 重写 paintEvent现有控件拼不出来的东西:仪表盘、波形图、流程图节点

正确的分工是:能用 QSS 解决的绝不自绘。QSS 一行能改的颜色,自绘要写十几行、还要处理禁用态、悬停态、不同 DPI。只有当需求超出标准控件的表达能力时,才动手写自绘控件,而且自绘控件内部仍应尽量通过 QStyle 绘制,以保持与平台观感一致。

#从零写一个自绘控件

一个规范的自定义控件至少要处理三件事:绘制、尺寸建议、状态反馈。下面实现一个"电池电量"控件:

C++
// 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 生态"的关键一步。

C++
// 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);
    }
}

三个必须记住的约定:

  1. 构造 QPainter p(this),不要 new。它必须在栈上,析构时自动 end();忘了 end() 会导致绘制不完整。
  2. 用 update() 而不是 repaint()。update() 只是"贴一张需要重绘的便签",Qt 会在下一个事件循环中合并多次请求;repaint() 是立即同步绘制,滥用会拖垮性能。
  3. sizeHint() / minimumSizeHint() 决定布局中的默认尺寸。不重写它们,布局系统会给出一个莫名其妙的默认值。

#让属性动起来

声明了 Q_PROPERTY 后,几行代码就能做平滑动画:

C++
#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)机制:

  1. 在 Designer 里拖一个 QWidget 到窗体上;
  2. 右键 → 提升为…;
  3. 填写"提升的类名称":Battery,"头文件":battery.h;
  4. 点击"添加",再点"提升"。

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 实例
IDQPushButton#okBtn { }objectName 为 okBtn 的按钮
属性QPushButton[flat="false"] { }属性值匹配
后代QDialog QPushButton { }Dialog 内所有层级的按钮
子代QDialog > QPushButton { }仅直接子对象
通配* { }所有控件

#盒模型与常用属性

QSS 的盒模型与 CSS 一致:margin → border → padding → content。绘制背景时最关键的是 background-clip——它决定背景绘制到哪一层。

Text
/* 通用按钮:扁平风格 —— 保存为 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。
C++
#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 使用。

#小结

  1. 美化优先用 QSS,标准控件无法表达时才自绘;自绘控件内部应尽量调用 QStyle 以保持原生观感。
  2. 自定义控件三要素:paintEvent() 绘制、sizeHint() 给尺寸建议、Q_PROPERTY 接入属性系统与动画框架。
  3. 刷新用 update()(异步合并)而非 repaint()(同步立即);QPainter 必须在栈上构造。
  4. QSS 选择器支持类型、ID、属性、后代与子控件(::);伪状态的书写顺序决定优先级。
  5. QSS 会用 QStyleSheetStyle 代理控件,使该子树的 QPalette 基本失效——全局主题用 Palette + Fusion,局部定制用 QSS。

#练习

  1. 给 Battery 加一个 warningThreshold 属性,低于阈值时电量条闪烁(提示:QTimer + update())。
  2. 用「提升」机制把 Battery 放进一个 .ui 文件,并在 Designer 属性编辑器中直接设置 value。
  3. 写一份全局 QSS,统一 QPushButton、QLineEdit、QTableView、QScrollBar 的样式,实现浅色/深色两套主题并支持运行时热切换。
  4. 实现一个自绘的"圆形进度环"控件,支持 value、lineWidth、startAngle 三个属性,并用 QPropertyAnimation 做入场动画。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。