文章

QSS

QSS（Qt Style Sheets）用于美化 Qt 界面，语法类似 CSS，可控制控件颜色、边框、字体、背景等外观，支持状态伪类与对象选择器。

发表于 更新于
作者 Sylvan
7 分钟阅读
QSS

QSS

QSS（Qt Style Sheets）是 Qt 的样式系统，用于美化控件，控制控件的颜色、边框、字体、背景、间距等外观效果。它的语法类似于 Web 的 CSS，但有自己的限制和扩展。

QSS 的应用方式

QSS 可以通过以下方式应用：

方式说明
widget->setStyleSheet()应用于单个控件
parent->setStyleSheet()应用于父控件及其所有子控件
qApp->setStyleSheet()全局应用，影响整个应用程序
Qt Designer 中设置样式UI 设计时直接设置

选择器类型

类型选择器

1
2

QPushButton { ... }
QLabel { ... }

作用于所有该类型的控件。

对象名选择器（ID选择器）

1

#submitButton { ... }

仅作用于 objectName 为 submitButton 的控件。

类型 + 对象名

1

QPushButton#submitButton { ... }

更精确，必须同时匹配类型和 objectName。

嵌套（后代）选择器

1

QDialog QPushButton { ... }

作用于 QDialog 内部所有 QPushButton。

伪状态选择器

状态说明
:hover鼠标悬停时
:pressed鼠标按下时
:checked被选中（复选框等）
:disabled控件不可用时
:focus获取键盘焦点时
:selected被选中（列表/树/表等）

伪元素选择器

元素说明
::item用于列表、树、表条目
::section用于表头
::indicator用于复选框/单选按钮指示器部分
::chunk用于 QProgressBar 的进度部分
::handle滑块、分割条
::branch用于树的分支图标

常见控件样式写法

QPushButton

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

QPushButton {
    background-color: #444;
    color: white;
    border: 1px solid #666;
    border-radius: 5px;
}
QPushButton:hover {
    background-color: #666;
}
QPushButton:pressed {
    background-color: #222;
}
QPushButton:disabled {
    color: gray;
    background-color: #333;
}

QLabel

1
2
3
4
5
6
7
8

QLabel {
    color: #ddd;
    font-size: 14px;
}
QLabel#title {
    font-weight: bold;
    font-size: 18px;
}

QLineEdit

1
2
3
4
5
6
7
8
9

QLineEdit {
    background-color: #222;
    color: white;
    border: 1px solid #555;
    border-radius: 3px;
}
QLineEdit:focus {
    border-color: #3399ff;
}

QListWidget / QTreeView

1
2
3
4
5
6
7
8

QListWidget::item:selected,
QTreeView::item:selected {
    background-color: #3399ff;
    color: white;
}
QListWidget::item:hover {
    background-color: #444;
}

QCheckBox

1
2
3
4
5
6
7
8
9

QCheckBox {
    color: white;
}
QCheckBox::indicator:checked {
    image: url(:/icons/checked.png);
}
QCheckBox::indicator:unchecked {
    image: url(:/icons/unchecked.png);
}

QScrollBar

1
2
3
4
5
6
7
8

QScrollBar:vertical {
    background: #2e2e2e;
    width: 10px;
}
QScrollBar::handle:vertical {
    background: #555;
    border-radius: 4px;
}

QProgressBar

1
2
3
4
5
6
7
8

QProgressBar {
    border: 1px solid #444;
    text-align: center;
    background-color: #222;
}
QProgressBar::chunk {
    background-color: #3399ff;
}

QToolTip

1
2
3
4
5
6
7

QToolTip {
    background-color: #333;
    color: white;
    border: 1px solid #555;
    padding: 4px;
    border-radius: 5px;
}

QSS 不生效的原因

  1. 控件 objectName 不正确（比如 labelPro 写成了 label_pro）
  2. 样式设置过早或设置在错误的控件上
  3. 被代码中的 setPalette()、setStyle() 或 setFont() 等覆盖
  4. 图片路径错误（不是 :/resource 格式）
  5. 控件被其他控件遮挡或透明

进阶技巧

  • 可以在运行时切换不同的 QSS 实现“换肤”
  • 可以在 QSS 中引用资源系统的图片：url(:/images/button.png)
  • 利用控件的 property 和 dynamicProperty 结合代码控制样式（可实现状态类切换）

一个完整 QSS 片段（暗色主题）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

QMainWindow {
    background-color: #2e2f30;
}

QPushButton {
    background-color: #444;
    color: white;
    border: 1px solid #666;
    border-radius: 4px;
}
QPushButton:hover {
    background-color: #555;
}
QPushButton:pressed {
    background-color: #333;
}
QLineEdit {
    background-color: #333;
    color: white;
    border: 1px solid #555;
    padding: 4px;
}
QListWidget::item:selected {
    background-color: #007acc;
    color: white;
}
QScrollBar:vertical {
    background: #222;
    width: 8px;
}
QScrollBar::handle:vertical {
    background: #555;
    border-radius: 4px;
}

Qt 样式优先级

优先级来源是否会覆盖 QSS示例
1️⃣代码设置：setPalette() / setFont() / setStyle() 等✅ 是label->setFont(...)
2️⃣UI 文件中手动设置的属性✅ 是Qt Designer 设置颜色、字体等
3️⃣控件的 QSS（setStyleSheet 或 qApp->setStyleSheet）✅ 中等label->setStyleSheet(...)
4️⃣控件的默认外观（系统主题样式）❌ 被覆盖未设置颜色、字体，系统默认的样子

代码设置（最高优先级）

1
2

label->setFont(QFont("微软雅黑", 18));
label->setPalette(...);

  • 优先级最高，会直接覆盖 QSS。

  • 设置了字体、颜色、边框等，即使在 QSS 中设了，也不会生效。

UI 文件中的属性设置（Designer 里设置的）

  • 在 Qt Designer 中选中一个控件，然后在属性编辑器里设置字体、前景色、背景色等。
  • Qt 会将其转化为代码等效形式（在构造时调用 setFont()、setPalette()），和手动代码设置效果一样，优先级高于 QSS。

解决方式：不要在 UI 文件里设置这些属性，把它们交给 QSS 控制。

QSS 设置（样式表）

包括以下几种方式：

1
2

qApp->setStyleSheet("QLabel { color: red; }");         // 全局 QSS
label->setStyleSheet("color: red;");                   // 局部 QSS
  • QSS 在没有代码或 UI 设置属性时，是有效的；
  • QSS 设置后，可以统一控件外观；
  • 它是非常灵活的，但被代码/UI 显式设置时可能被部分覆盖。

默认样式（系统主题）

  • 当什么都不设置时，Qt 会使用系统风格，如 Windows/ macOS / Fusion 样式。
  • 默认值是最低的，几乎总是可以被 QSS 覆盖。

避免 QSS 无效的建议

  1. 不要在 Qt Designer 中设置字体、颜色、背景等外观属性；
  2. 不要在代码中调用 setFont()、setPalette()，除非不打算用 QSS 控制外观；
  3. 推荐统一使用 QSS 控制界面主题，集中管理样式逻辑；
  4. 如果 QSS 仍然不生效，确保 objectName 是否正确、资源路径是否加载成功。

示例对比

1
2
3
4
5

label->setFont(QFont("宋体", 20)); // 优先级最高，覆盖QSS字体设置

label->setStyleSheet("font-size: 14px; color: red;"); // 优先级中等

// UI中设置了字体=宋体12号，也会影响QSS
qt, qt basics
Qt
本文由作者按照 CC BY 4.0 进行授权