Qt 控件 QSS 样式大全（通用属性篇）

本篇聚焦于 Qt Style Sheets（QSS）中所有 QWidget 及其子类可共享的通用样式属性，帮助你快速搭建统一的视觉主题并为后续控件专章铺垫基础。

如何使用本文档

面向人群：希望建立 Qt 全局主题、设计系统或需要快速查阅属性效果的开发者与 UI 设计师。

阅读方式：先通览内容导览了解分类，再按需定位到具体属性段落；每个子节包含"属性表 + 使用说明 + 实战示例"三部分。

配套建议：边阅读边在沙箱项目中尝试，结合 Qt Designer/Creator 的实时预览验证效果。

内容导览

QSS 应用基础
- 1.1 加载方式
- 1.2 基础语法要点
- 1.3 继承与优先级规则
通用属性分类索引
分类详解
- 3.1 文字与排版
- 3.2 背景与填充
- 3.3 边框与圆角
- 3.4 盒模型与布局
- 3.5 尺寸与对齐
- 3.6 图像与图标资源
- 3.7 交互反馈：焦点、轮廓与状态
- 3.8 光标与可访问性
- 3.9 高级效果与 qproperty
伪状态、属性选择器与层叠策略
常用主题片段示例
调试、性能与团队协作建议
版本兼容与常见坑列表

1. QSS 应用基础

1.1 加载方式

全局样式（C++）

cpp 复制代码

QFile file(":/style/app.qss");
if (file.open(QIODevice::ReadOnly)) {
  qApp->setStyleSheet(QString::fromUtf8(file.readAll()));
}

在 main() 初始化阶段加载，作用于整个应用，适合统一主题。

局部样式（C++）

cpp 复制代码

auto button = new QPushButton("提交");
button->setStyleSheet("QPushButton { padding: 6px 12px; }");

仅影响目标控件及其子控件，便于临时自定义。

PyQt/PySide

python 复制代码

with open("style/app.qss", encoding="utf-8") as f:
  app.setStyleSheet(f.read())

与 C++ 相同的语法，注意文件编码。

动态属性驱动主题
cpp 复制代码
```
widget->setProperty("tone", "primary");
widget->style()->unpolish(widget);
widget->style()->polish(widget);
```
配合属性选择器实现主题切换，需重新 polish 以刷新样式。

1.2 基础语法要点

使用 ; 结束属性声明，块内换行不影响解析。

支持 CSS 注释 /* ... */，不支持 //。

支持 url(:/...) 引用 Qt 资源或磁盘文件，相对路径基于样式文件所在目录。

若背景未生效，确认目标控件调用了 setAttribute(Qt::WA_StyledBackground, true);。

Qt 内部使用像素单位，pt、em 会被转换为像素；建议直接使用 px。

1.3 继承与优先级规则

选择器优先级 ：QWidget#mainPanel QPushButton > QWidget QPushButton > QPushButton > *。

层叠顺序：后声明覆盖先声明；同一选择器的后续属性会替换前面的值。

继承属性：字体、颜色等文本属性会沿控件树向下继承；背景、边框等盒模型属性默认不会继承。

状态覆盖 ：伪状态（:hover、:pressed、:disabled 等）优先于普通规则。

平台差异：部分原生控件在 macOS/Windows 上可能忽视部分 QSS 属性，需要关闭原生样式或改用代理控件。

2. 通用属性分类索引

大类	小类	典型属性	核心用途
文字与排版	颜色、字体、文本装饰	`color`、`selection-color`、`font-family`、`font-weight`、`font-letter-spacing`、`font-underline`	控制文本呈现、选区配色、字体细节
背景与填充	纯色、渐变、图片	`background-color`、`background`、`background-image`、`background-repeat`、`background-position`	填充控件背景、构建渐变或纹理
边框与圆角	线框、九宫格	`border`、`border-top-width`、`border-radius`、`border-image`、`border-image-slice`	勾勒轮廓、实现卡片化外观
盒模型与布局	内外边距	`padding`、`margin`、`spacing`（布局属性）	调整控件自身间距与布局中的占位
尺寸与对齐	最小/最大/固定尺寸	`min-width`、`max-height`、`width`、`height`、`qproperty-alignment`	控制控件尺寸约束与内容对齐
图像与图标资源	图标、遮罩	`icon-size`、`image`、`border-image`	统一按钮/工具栏图标尺寸，设置背景切片
交互反馈	焦点、选中、禁用	`outline`、`outline-offset`、伪状态覆盖	强调交互变化，提高可用性
光标与可访问性	鼠标形状、透明度	`cursor`、`opacity`、`qproperty-toolTipDuration`	提示可交互区域、控制透明度
高级效果	发光、投影、动画	`box-shadow`（Qt 6.5+）、`qproperty-graphicsEffect`	实现高级质感，需注意版本兼容

3. 分类详解

3.1 文字与排版

3.1.1 属性与效果

属性	支持版本	取值类型	视觉效果	示例片段
`color`	Qt 4+	颜色值	设置文本颜色，可继承	`color: #1F2A37;`
`selection-color`	Qt 4+	颜色值	选中文本前景色	`selection-color: white;`
`selection-background-color`	Qt 4+	颜色值	选中文本背景色	`selection-background-color: #409EFF;`
`alternate-background-color`	Qt 4+	颜色值	表格/列表交替行底色	`alternate-background-color: #f8f9fb;`
`font-family`	Qt 4+	字体名称	指定字体族	`font-family: "Microsoft YaHei";`
`font-size`	Qt 4+	长度值	指定字号	`font-size: 14px;`
`font-weight`	Qt 4+	100--900 或 `bold`	控制字重	`font-weight: 600;`
`font-style`	Qt 4+	`normal`/`italic`	文字倾斜	`font-style: italic;`
`font-letter-spacing`	Qt 5+	长度值	调整字符间距	`font-letter-spacing: 0.5px;`
`font-variant`	Qt 4+	`normal`/`small-caps`	小型大写字母	`font-variant: small-caps;`
`font-underline`/`overline`/`strikeout`	Qt 4+	`true`/`false`	文本附加线条	`font-underline: true;`
`font-capitalization`	Qt 4+	`none`/`all-uppercase` 等	自动大小写转换	`font-capitalization: all-uppercase;`

3.1.2 使用说明

字体属性具有继承性，建议在 QApplication 或根控件统一设置，再按需覆盖。

淡化禁用态可通过 color 配合 :disabled 指定半透明颜色。

可使用组合写法：font: 500 14px/20px "Source Han Sans";（权重 + 字号/行高 + 字体族）。

列表控件启用交替行颜色需在代码中调用 view->setAlternatingRowColors(true);。

3.1.3 实战示例

css 复制代码

QWidget {
  font: 400 14px/22px "Microsoft YaHei";
  color: #2f3542;
}

QLabel[role="caption"] {
  font-size: 12px;
  font-weight: 400;
  color: rgba(47, 53, 66, 0.65);
}

QLineEdit:disabled {
  color: rgba(47, 53, 66, 0.45);
  selection-background-color: rgba(64, 158, 255, 0.2);
}

3.2 背景与填充

3.2.1 属性与效果

属性	支持版本	取值类型	视觉效果	示例片段
`background-color`	Qt 4+	颜色/渐变	填充背景色	`background-color: #FFFFFF;`
`background`	Qt 4+	复合值	同时指定颜色、图像、重复	`background: #fff url(:/bg/noise.png) repeat;`
`background-image`	Qt 4+	`url(...)`	设置背景图	`background-image: url(:/bg/panel.svg);`
`background-repeat`	Qt 4+	`repeat`/`no-repeat` 等	控制平铺方式	`background-repeat: no-repeat;`
`background-position`	Qt 4+	长度/百分比/方位词	控制背景定位	`background-position: center;`
`background-origin`	Qt 4+	`content`/`padding`/`border`	定义定位参考	`background-origin: content;`
`background-clip`	Qt 4+	同上	定义裁剪边界	`background-clip: padding;`
`palette(<role>)`	Qt 4+	调色板颜色角色	引用调色板颜色	`background-color: palette(window);`
渐变函数	Qt 4+	`qlineargradient` 等	生成渐变背景	`background-color: qlineargradient(...);`
`qradialgradient()`	Qt 4+	圆形渐变	构造径向渐变	`background: qradialgradient(cx:0.5,cy:0.5,r:0.6, stop:0 #fff, stop:1 #cbd5f5);`
`qconicalgradient()`	Qt 4+	锥形渐变	构造仪表盘类渐变	`background: qconicalgradient(cx:0.5,cy:0.5, angle:90, stop:0 #2563eb, stop:1 #60a5fa);`

3.2.2 使用说明

QWidget 默认不绘制自身背景，若背景未生效需调用 setAttribute(Qt::WA_StyledBackground, true);。

渐变语法与 QBrush 一致，支持色标 stop:0 #fff, stop:1 #eee。

Qt 不支持多层背景叠加，如需复合效果可使用多层容器或预渲染图像。

配合 border-radius 时，背景图默认裁剪为圆角矩形，可通过 background-clip: border; 调整。

3.2.3 实战示例

css 复制代码

QWidget[type="card"] {
  background: qlineargradient(
    x1: 0,
    y1: 0,
    x2: 0,
    y2: 1,
    stop: 0 #ffffff,
    stop: 1 #f5f7fb
  );
  background-clip: padding;
  background-origin: padding;
}

3.3 边框与圆角

3.3.1 属性与效果

属性	支持版本	取值类型	视觉效果	示例片段
`border`	Qt 4+	`<width> <style> <color>`	一次性设定边框	`border: 1px solid rgba(27, 38, 59, 0.12);`
`border-style`	Qt 4+	`solid`/`dashed`/`dotted` 等	指定线型	`border-style: dashed;`
`border-*-width/color/style`	Qt 4+	细化属性	四边独立控制	`border-bottom-width: 2px;`
`border-radius`	Qt 4+	长度值	设置圆角	`border-radius: 12px;`
`border-top-left-radius` 等	Qt 4+	长度值	控制单个角	`border-top-left-radius: 16px;`
`border-image`	Qt 4+	`url + slice`	九宫格拉伸	`border-image: url(:/frame/panel.png) 16 16 16 16 stretch;`
`border-image-repeat`	Qt 5+	`stretch`/`repeat`/`round`	控制平铺模式	`border-image-repeat: round;`
`outline`	Qt 4+	线性盒外轮廓	焦点提示，不占布局	`outline: 2px solid #409EFF;`
`outline-offset`	Qt 4+	长度值	调整轮廓距离控件的间距	`outline-offset: 2px;`

3.3.2 使用说明

border-image 将覆盖常规边框属性，但仍需设置 border-width 或 border-style 以启用绘制。

圆角配合 border-image 时需保证源图透明区域充足，避免锯齿。

虚线或点线边框在 HiDPI 下可能锯齿，可考虑使用背景图。

与伪状态组合可实现不同交互状态下的边框高亮。

3.3.3 实战示例

css 复制代码

QWidget[type="elevated"] {
  border: 1px solid rgba(15, 23, 42, 0.12);
  border-radius: 10px;
  background-color: #ffffff;
}

QWidget[type="elevated"]:hover {
  border-color: rgba(64, 158, 255, 0.65);
}

QWidget[type="frame"] {
  border-image: url(:/frame/rounded.png) 24 24 24 24 stretch;
}

3.4 盒模型与布局

3.4.1 属性与效果

属性	支持版本	取值类型	视觉效果	示例片段
`padding`	Qt 4+	长度值	内容与边框之间的内边距	`padding: 8px 12px;`
`padding-*`	Qt 4+	长度值	四向独立控制	`padding-left: 16px;`
`margin`	Qt 4+	长度值	控件与外部的间距（受布局影响）	`margin: 6px 0;`
`margin-*`	Qt 4+	长度值	四向独立	`margin-bottom: 12px;`
`spacing`（布局）	Qt 4+	长度值	控制布局内控件间距	`QVBoxLayout { spacing: 12px; }`
`qproperty-contentsMargins`	Qt 4+	`left top right bottom`	设置布局内容边距	`qproperty-contentsMargins: 12 12 12 12;`

3.4.2 使用说明

margin 仅对未受布局管理的控件生效；在布局中需调整 setContentsMargins() 与 setSpacing()。

padding 为按钮、标签提供更舒适的触控与阅读间距。

当 border-radius > 0 时，确保 padding 足够，避免内容贴近圆角。

3.4.3 实战示例

css 复制代码

QPushButton {
  padding: 6px 16px;
  margin: 4px;
  border-radius: 8px;
}

QWidget[type="card"] {
  padding: 16px 20px 12px;
}

QVBoxLayout {
  spacing: 10px;
  qproperty-contentsmargins: 12 12 12 12;
}

3.5 尺寸与对齐

3.5.1 属性与效果

属性	支持版本	取值类型	视觉效果	示例片段
`min-width`、`min-height`	Qt 4+	长度值	限制最小尺寸	`min-width: 120px;`
`max-width`、`max-height`	Qt 4+	长度值	限制最大尺寸	`max-height: 36px;`
`width`、`height`	Qt 4+	长度值	尝试固定尺寸	`height: 32px;`
`qproperty-sizeHint`	Qt 5+	`width height`	指定推荐尺寸	`qproperty-sizeHint: 120 36;`
`qproperty-alignment`	Qt 4+	Qt::Alignment 标志	控制内容对齐	`qproperty-alignment: AlignLeft
`qproperty-wordWrap`	Qt 4+	`true`/`false`	控制换行	`qproperty-wordWrap: true;`

3.5.2 使用说明

若控件受布局管理，width/height 可能被忽略，推荐使用 min-/max- 系列组合。

sizePolicy 仍需在代码层配置，QSS 主要负责视觉约束。

qproperty- 前缀允许直接设置公开属性，需确认目标类拥有对应属性。

3.5.3 实战示例

css 复制代码

QPushButton[type="cta"] {
  min-width: 160px;
  min-height: 40px;
  qproperty-sizehint: 160 40;
}

QLabel[role="title"] {
  qproperty-alignment: AlignLeft | AlignVCenter;
  font-size: 18px;
}

3.6 图像与图标资源

3.6.1 属性与效果

属性	支持版本	取值类型	视觉效果	示例片段
`image`	Qt 4+	`url(...)`	设置控件背景图像（多用于子控件）	`image: url(:/icons/checked.svg);`
`border-image`	Qt 4+	`url + slice`	九宫格背景（详见 3.3）	`border-image: url(:/frame/input.png) 8 8 8 8;`
`icon-size`	Qt 4+	长度对	控制按钮或工具栏图标尺寸	`icon-size: 20px 20px;`
`qproperty-icon`	Qt 4+	`url(...)`	直接为按钮等设置图标	`qproperty-icon: url(:/icons/add.svg);`
`qproperty-pixmap`	Qt 4+	`url(...)`	为 `QLabel` 等设置像素图	`qproperty-pixmap: url(:/banner.png);`
`qproperty-iconSize`	Qt 4+	`QSize(w,h)`	直接设置按钮图标尺寸	`qproperty-iconSize: QSize(24, 24);`

3.6.2 使用说明

image 常用于 QCheckBox::indicator、QRadioButton::indicator 等子控件，需要结合伪元素选择器。

SVG 图标在 HiDPI 下表现最佳；PNG 需提供多倍图并启用 AA_UseHighDpiPixmaps。

配合 icon-size 与合适 padding，可保证图标按钮的触控面积与布局一致。

3.6.3 实战示例

css 复制代码

QPushButton[type="icon"] {
  min-width: 32px;
  min-height: 32px;
  icon-size: 18px 18px;
  padding: 6px;
}

QPushButton[type="icon"]::menu-indicator {
  image: url(:/icons/chevron-down.svg);
}

3.7 交互反馈：焦点、轮廓与状态

3.7.1 属性与效果

属性/状态	说明	示例
`outline` + `outline-offset`	自定义焦点高亮，不占用布局	`outline: 2px solid #409EFF; outline-offset: 2px;`
`:hover`	鼠标悬停状态	`QPushButton:hover { background-color: #eff6ff; }`
`:pressed`	鼠标按下未释放	`QPushButton:pressed { background-color: #dbeafe; }`
`:checked`/`:unchecked`	适用可选项控件	`QCheckBox:checked { color: #409EFF; }`
`:disabled`	禁用态	`color: rgba(47,53,66,0.45);`
`:focus`	键盘焦点	常配合 outline、阴影高亮
`:indeterminate`	三态勾选	表示部分状态
`:window`	顶层窗口	用于区分顶层与子容器

3.7.2 使用说明

若要去除系统默认焦点框，需 outline: none; 并自定义 :focus 样式，以保持键盘可访问性。

:hover 与 :pressed 常用于按钮或列表项，推荐同步调整边框与阴影以突出层次。

Qt 6.5+ 对 transition 有基础支持，但为实验特性，旧版本需通过动画框架实现过渡效果。

3.7.3 实战示例

css 复制代码

QPushButton[type="primary"] {
  background-color: #2563eb;
  color: #ffffff;
  border-radius: 6px;
  outline: none;
  transition: background-color 120ms ease;
}

QPushButton[type="primary"]:hover {
  background-color: #1d4ed8;
}

QPushButton[type="primary"]:pressed {
  background-color: #1e40af;
}

QPushButton[type="primary"]:focus-visible {
  outline: 2px solid rgba(37, 99, 235, 0.55);
  outline-offset: 2px;
}

3.8 光标与可访问性

3.8.1 属性与效果

属性	支持版本	取值类型	视觉效果	示例片段
`cursor`	Qt 4+	Qt 光标名称	更改鼠标指针	`cursor: pointing-hand;`
`opacity`	Qt 6.6+	0.0--1.0 浮点	控制控件透明度	`opacity: 0.8;`
`qproperty-toolTip`	Qt 4+	文本/HTML	设置悬浮提示	`qproperty-toolTip: "快捷键：Ctrl+S";`
`qproperty-toolTipDuration`	Qt 4+	整数（毫秒）	控制提示保持时间	`qproperty-toolTipDuration: 3000;`
`qproperty-whatsThis`	Qt 4+	文本/HTML	设置 What's This 提示	`qproperty-whatsThis: "详细帮助";`

3.8.2 使用说明

鼠标形状名称与 Qt::CursorShape 枚举一致，如 pointing-hand、ibeam、cross 等。

opacity 在旧版本不可用，需通过 setWindowOpacity() 或 QGraphicsOpacityEffect 实现。

工具提示支持富文本，可结合 QSS 设置 QToolTip 样式提升可访问性

3.9 高级效果与 qproperty

3.9.1 属性与效果

属性	支持版本	功能	示例
`box-shadow`	Qt 6.5+（实验）	添加阴影、发光效果	`box-shadow: 0 8px 20px rgba(15,23,42,0.18);`
`qproperty-graphicsEffect`	Qt 4+	绑定 `QGraphicsEffect` 对象	`qproperty-graphicsEffect: glowEffect;`（需代码设置对象名）
`qproperty-styleSheet`	Qt 4+	为子控件注入局部样式	谨慎使用，易递归
自定义动态属性	Qt 4+	配合属性选择器实现主题切换	`QWidget[tone="warning"] { ... }`

3.9.2 使用说明

box-shadow 尚未完全覆盖所有平台，使用前请在目标系统验证。

qproperty-graphicsEffect 需在代码中创建 QGraphicsDropShadowEffect 等并为对象命名。

动态属性比较基于字符串；数值型属性建议转成字符串以确保匹配。

4. 伪状态、属性选择器与层叠策略

4.1 常用伪状态对照

伪状态	适用控件	触发条件	常见用途
`:hover`	所有 QWidget	鼠标位于控件上方	高亮背景、边框
`:pressed`	可点击控件	鼠标按下未释放	按钮压下反馈
`:checked`	复选框、单选框、切换按钮	被选中	显示激活状态
`:focus`	可聚焦控件	获得键盘焦点	键盘导航提示
`:focus-visible`（Qt 6+）	可聚焦控件	键盘或辅助设备聚焦	区分鼠标与键盘
`:disabled`	所有	`setEnabled(false)`	禁用态降对比
`:indeterminate`	三态控件	部分选中	部分状态提示
`:read-only`	可编辑控件	只读	提示不可编辑
`:window`	顶层 QWidget	控件为窗口	区分顶层容器

4.2 属性选择器与动态主题

设置属性 ：widget->setProperty("tone", "primary");

QSS 写法 ：QPushButton[tone="primary"] { ... }

组合使用 ：QPushButton[tone="danger"]:hover { ... }

属性值以字符串比较，数值型属性需转为字符串或注意格式差异。

4.3 层叠策略建议

使用通配 * 或 QWidget 定义基础主题。

为组件族（如 QAbstractButton）定义中间层样式，减少重复。

通过属性、对象名或层级选择器实现特化，以免影响全局。

将伪状态规则紧随对应常规规则，便于覆盖与维护。

将复杂样式拆分为多个逻辑块，保持文件结构清晰。

5. 常用主题片段示例

5.1 卡片容器

css 复制代码

QWidget[type="card"] {
  background-color: #ffffff;
  border-radius: 12px;
  border: 1px solid rgba(15, 23, 42, 0.08);
  padding: 16px 20px;
  box-shadow: 0 12px 24px rgba(15, 23, 42, 0.08);
}

QWidget[type="card"][priority="high"] {
  border-color: rgba(37, 99, 235, 0.55);
  box-shadow: 0 16px 32px rgba(37, 99, 235, 0.18);
}

5.2 输入框主题

css 复制代码

QLineEdit {
  padding: 6px 10px;
  border: 1px solid rgba(148, 163, 184, 0.6);
  border-radius: 6px;
  background-color: #ffffff;
  selection-background-color: rgba(37, 99, 235, 0.18);
}

QLineEdit:focus {
  border-color: #2563eb;
  outline: 2px solid rgba(37, 99, 235, 0.28);
  outline-offset: 1px;
}

QLineEdit:disabled {
  background-color: rgba(241, 245, 249, 0.9);
  color: rgba(30, 41, 59, 0.45);
}

5.3 工具栏按钮

css 复制代码

QToolButton {
  icon-size: 18px 18px;
  padding: 6px;
  border-radius: 6px;
  background-color: transparent;
  cursor: pointing-hand;
  transition: background-color 120ms ease;
}

QToolButton:hover {
  background-color: rgba(37, 99, 235, 0.12);
}

QToolButton:checked {
  background-color: rgba(37, 99, 235, 0.18);
}

6. 调试、性能与团队协作建议

实时热更新 ：开发时将 QSS 放在独立文件，结合 QFileSystemWatcher 自动重新加载。

分模块管理 ：按控件或功能拆分 .qss 文件，最终使用 @import（Qt 5.15+）或脚本合并，便于协作。

命名规范 ：统一对象名、动态属性命名（如 tone="primary"、state="warning"）提升可读性。

性能考量 ：大面积渐变、透明度叠加会增加绘制成本，可缓存 QPixmap 或降低刷新频率。

跨平台测试：在 Windows、macOS、Linux 下逐一验证，关注系统默认主题的影响。

与设计协同：约定颜色、字号、阴影等设计 tokens，在 QSS 中通过注释或预处理器维护。

7. 版本兼容与常见坑列表

项目	影响版本	说明	解决方案
`box-shadow`	Qt < 6.5	不支持该属性	使用 `QGraphicsDropShadowEffect` 或预制 PNG 阴影
`opacity` 属性	Qt < 6.6	不识别透明度	调用 `setWindowOpacity()` 或使用 `QGraphicsOpacityEffect`
macOS 原生按钮	Qt 5.x	部分 QSS 被原生样式覆盖	关闭原生主题或使用 `QProxyStyle` 替换
背景失效	全版本	QWidget 默认不绘制背景	调用 `setAttribute(Qt::WA_StyledBackground, true);`
圆角+图片锯齿	HiDPI	边缘不平滑	使用 SVG 或高分辨率资源，启用 `AA_UseHighDpiPixmaps`
属性选择器无效	Qt 5	属性未刷新	设置属性后调用 `style()->unpolish/polish` 或重新应用样式

基于以上分类与实例，你可以为任意 Qt 控件快速搭建一致的视觉风格。下一阶段可在此基础上针对
QPushButton、QLineEdit、QTableView 等控件编写专用样式章节，逐步完善完整的 Qt 主题设计手册。