预计阅读时间：5 分钟
PyQt5 QSS（Qt Style Sheets）完整语法手册
Qt Style Sheets（QSS）是 PyQt5 / PySide2 用于定义控件外观的语言，
语法类似 CSS，但有自己的一套规则和限制。
🧱 一、基础语法结构
QSS 基本结构与 CSS 类似：
选择器 {
属性名: 属性值;
属性名: 属性值;
}
多个样式可连写：
QPushButton, QToolButton {
color: white;
background-color: #3b5998;
}
🧩 二、选择器类型
1️⃣ 控件名选择器
直接使用控件类名：
QPushButton { color: white; }
QLineEdit { background-color: #eee; }
2️⃣ 对象名选择器（#）
使用 setObjectName() 指定后，用 # 选择：
#submitBtn { background-color: green; }
3️⃣ 类选择器（.）
QSS 也支持 property 属性模拟 class：
button.setProperty("class", "danger")
然后：
QPushButton.danger { background-color: red; }
4️⃣ 继承层级选择器
QGroupBox QPushButton {
color: blue;
}
5️⃣ 子控件选择器
指定控件内部的子元素：
QComboBox QAbstractItemView { background: white; }
QScrollBar::handle { background: gray; }
🧠 三、伪状态（Pseudo-States）
| 状态 | 说明 |
|---|---|
:hover |
鼠标悬停时 |
:pressed |
鼠标按下 |
:checked |
复选框、单选框、开关选中状态 |
:unchecked |
未选中 |
:disabled |
禁用状态 |
:enabled |
启用状态 |
:focus |
获取焦点时 |
:read-only |
只读状态 |
:on / :off |
菜单、按钮的切换状态 |
:indeterminate |
复选框不确定状态 |
示例：
QPushButton:hover { background-color: #5b9bd5; }
QPushButton:pressed { background-color: #2e75b6; }
QPushButton:disabled { color: gray; }
🎨 四、常用属性分类
1️⃣ 背景与前景
background-color: #f0f0f0;
background-image: url(:/img/bg.png);
color: #333;
2️⃣ 边框样式
border: 1px solid #ccc;
border-radius: 6px;
border-top: 2px dashed red;
3️⃣ 字体样式
font-family: "Microsoft YaHei";
font-size: 14px;
font-weight: bold;
font-style: italic;
4️⃣ 内外边距
padding: 4px 8px;
margin: 2px;
5️⃣ 对齐方式（仅部分控件支持）
qproperty-alignment: AlignCenter;
6️⃣ 尺寸与几何属性
min-width: 100px;
max-width: 300px;
min-height: 30px;
🔸 五、控件专属伪元素（Sub-controls）
某些控件内部有可独立设置的“子部分”：
QScrollBar::handle
QScrollBar::add-line
QScrollBar::sub-line
QComboBox::drop-down
QProgressBar::chunk
QSlider::groove
QSlider::handle
示例：
QScrollBar::handle:vertical {
background: #aaa;
border-radius: 3px;
}
QComboBox::drop-down {
border-left: 1px solid #666;
width: 20px;
}
🧰 六、属性绑定（qproperty）
可以绑定 Qt 属性：
qproperty-icon: url(:/icons/add.png);
qproperty-alignment: AlignCenter;
适用于：QLabel, QPushButton, QCheckBox 等。
⚙️ 七、继承与层叠规则
- 控件自己的样式 > 父控件样式 > 全局样式
- 相同选择器后定义的样式会覆盖前面的
- QSS 不会自动继承字体和颜色，除非明确定义
🧱 八、函数与值类型
QSS 支持一些 Qt 特有函数：
rgb(255, 0, 0)
rgba(0, 0, 0, 0.5)
url(:/images/bg.png)
qlineargradient(x1:0, y1:0, x2:1, y2:0, stop:0 red, stop:1 blue)
示例：
QProgressBar::chunk {
background: qlineargradient(
x1:0, y1:0, x2:0, y2:1,
stop:0 #05B8CC, stop:1 #0078A8
);
}
💡 九、示例：综合界面样式
QWidget {
background-color: #2e2e2e;
color: #f0f0f0;
font-family: "Microsoft YaHei";
font-size: 14px;
}
QLineEdit {
background-color: #3a3a3a;
border: 1px solid #555;
border-radius: 5px;
padding: 4px 8px;
}
QPushButton {
background-color: #0078d7;
border: none;
color: white;
border-radius: 6px;
padding: 6px 12px;
}
QPushButton:hover { background-color: #0096ff; }
QPushButton:pressed { background-color: #005a9e; }
QPushButton:disabled { background-color: #555; color: #888; }
🧭 十、调试技巧
-
可将
.qss文件单独保存并加载：bash with open("style.qss", "r") as f: app.setStyleSheet(f.read()) -
Qt Designer 里可直接预览样式。
-
若样式不生效，检查：
- 控件名称是否正确
- 样式层级冲突
- 控件是否启用（enabled）
✅ 总结
QSS = CSS for Qt
语法结构与 CSS 相似，但： - 控件名取代 HTML 标签
- 属性集有限
- 支持 Qt 特有的伪元素和属性绑定
可通过 QSS 快速构建现代化 UI，而无需修改控件逻辑。
推荐实践：
- 用全局样式控制整体基调
- 对关键控件使用 #id 或 .class 微调
- 将 QSS 独立文件化方便维护
本文由 changchang 原创，转载请注明出处。