Qt 控件 QSS 样式大全（控件特性篇）

本篇聚焦各类 Qt 控件在 QSS 中的 特有样式入口、伪元素/子控件、常见视觉需求 和 实战代码片段，可与《通用属性篇》联动使用，快速搭建完整主题。

如何使用本文档

  • 定位控件：通过分类导览或搜索控件名称，找到对应章节。
  • 阅读顺序：每节均按“结构剖析 → 关键属性 → 伪状态 → 实战示例 → 进阶技巧”展开，必要时提供对照表。
  • 配套工具：结合 Qt Designer/Creator 或自制 Demo 工程，验证样式表影响；遇到子控件命名不清晰时，打开 Qt 文档或使用 setStyleSheet("* { border: 1px solid red; }") 方式定位。

分类导览

模块涵盖控件核心样式入口典型场景
1. 按钮与动作QAbstractButton、QPushButton、QToolButton、QCommandLinkButton主体、::menu-indicator、::indicator主按钮、图标按钮、菜单按钮、链接按钮
2. 切换控件QCheckBox、QRadioButton、自定义开关::indicator、:checked、:indeterminate复选框、单选、仿 iOS 开关
3. 文本与表单输入QLineEdit、QTextEdit、QPlainTextEdit、QSpinBox 等主体、::down-arrow、::up-button表单输入、搜索框、数值选择
4. 下拉与选择器QComboBox、QFontComboBox、QDateEdit::drop-down、::down-arrow、QAbstractItemView下拉菜单、日期选择
5. 滑动与滚动QSlider、QScrollBar、QDial::groove、::handle、::add-line滑块、滚动条、旋钮
6. 进度与状态QProgressBar、QLCDNumber、QProgressDialog::chunk、::item进度条、步骤状态展示
7. 视图与表头QListView、QTreeView、QTableView、QHeaderView::item、::section、:selected列表、树、表格主题化
8. 容器与结构QGroupBox、QFrame、QTabWidget、QScrollArea::title、::pane、::tab面板、分页、滚动容器
9. 菜单与工具栏QMenuBar、QMenu、QStatusBar、QToolBar::item、::separator顶部菜单、上下文菜单、状态栏
10. 对话与提示QDialog、QMessageBox、QToolTip、QStatusTipEvent主体、::label、::button提示气泡、消息框、对话按钮

术语说明：本文使用 “子控件/伪元素” 指代 QSS 中带 :: 的选择器，如 QComboBox::drop-down；“伪状态” 指代 :hover、:checked 等状态选择器。

1. 按钮与动作控件

1.1 QAbstractButton 通用特性

结构剖析
  • 主控件：QAbstractButton（基类，派生 QPushButton、QToolButton 等）
  • 子控件/伪元素：
    • ::menu-indicator：带菜单按钮的下拉箭头区域。
    • ::indicator：适用于复选/单选等派生类。
  • 常用伪状态：:hover、:pressed、:checked、:disabled、:focus、:default、:flat。
关键属性与效果
选择器/属性功能说明取值示例使用提示
QAbstractButton控制按钮主体padding: 6px 14px;建议统一最小尺寸，提升触控体验
QAbstractButton:hover悬停态反馈background: rgba(37, 99, 235, 0.08);与 :pressed 结合提供层级变化
QAbstractButton:pressed按下态padding-top: 7px;通过内边距变化模拟下沉感
QAbstractButton:default默认按钮样式border-color: #2563eb;QPushButton::setDefault(true) 时触发
QAbstractButton:disabled禁用态color: rgba(47, 53, 66, 0.45);降低对比度或透明度提醒不可用
QAbstractButton::menu-indicator菜单箭头区域image: url(:/icons/chevron-down.svg);可设置 width/height/padding 调整对齐
QAbstractButton::indicator带勾选功能的指示器width: 14px; height: 14px;适用于 QToolButton 的 checkable 模式
QAbstractButton + icon-size控制图标尺度icon-size: 20px 20px;保持图标按钮视觉一致
qproperty-icon设置按钮主图标qproperty-icon: url(:/icons/add.svg);适合纯图标按钮或工具栏
QAbstractButton:flat扁平化状态background: transparent;setFlat(true) 时触发，可重新定义悬停态
实战示例：主题化按钮基线
/* === 基础按钮：统一触控面积与排版 === */
QAbstractButton {
/* 保证垂直方向的可点击高度 */
min-height: 34px;
/* 保证水平方向最小宽度，避免文本过挤 */
min-width: 88px;
/* 内边距决定文本与边框的呼吸感 */
padding: 6px 18px;
/* 圆角打造卡片化风格 */
border-radius: 8px;
/* 预留边框，悬停/聚焦时可直接改色 */
border: 1px solid transparent;
/* 统一字重与字体族，提升视觉权重 */
font: 500 14px "Microsoft YaHei";
}
/* 默认按钮：突出主操作 */
QAbstractButton:default {
border-color: #2563eb;
background-color: rgba(37, 99, 235, 0.12);
}
/* 按下态：通过上下 padding 差模拟物理下压 */
QAbstractButton:pressed {
padding-top: 7px;
padding-bottom: 5px;
}
/* 菜单箭头：控制尺寸与对齐 */
QAbstractButton::menu-indicator {
width: 12px;
image: url(:/icons/chevron-down.svg);
subcontrol-origin: padding;
subcontrol-position: right center;
margin-left: 6px;
}
进阶技巧
  • 使用 setProperty("tone", "primary") + QAbstractButton[tone="primary"] 实现多色主题。
  • 对 ::menu-indicator 使用 transform 可自定义旋转动画（Qt 6.5+）。
  • :checked 可制造“保持高亮”的 Toggle Button，配合 QButtonGroup 互斥模式。

1.2 QPushButton

特有结构
  • :default、:flat 状态常与原生风格绑定，需明确覆盖策略。
  • ::menu-indicator 默认尺寸较小，可通过 padding 和 subcontrol-origin 调整。
  • 支持 icon-size、qproperty-icon 快速替换图标。
常用伪状态扩展
状态触发条件样式建议
:defaultsetDefault(true)通过边框或光晕强化主按钮
:hover鼠标悬停提升背景亮度或添加描边提醒可点击
:checkedsetCheckable(true) 被选中用作 Toggle、Segmented 按钮
:pressed鼠标按下轻微下沉或阴影减弱，保持按钮反馈一致
:focus键盘聚焦结合 outline 或边框色提升键盘导航可见性
:disabledsetEnabled(false)降低不透明度、禁用指针事件
:menu-indicator:open菜单展开改变箭头颜色或旋转指示当前打开状态
典型样式片段
/* 主色按钮：主操作、高亮 CTA */
QPushButton[tone="primary"] {
/* 填充品牌色 */
background-color: #2563eb;
/* 边框与背景同色，方便 hover 时换色 */
border-color: #2563eb;
/* 主按钮文字采用白色保证对比度 */
color: #ffffff;
}
/* 悬停：略微加深背景，强调可交互 */
QPushButton[tone="primary"]:hover {
background-color: #1d4ed8;
}
/* 禁用：降低透明度并去除边框强调 */
QPushButton[tone="primary"]:disabled {
background-color: rgba(37, 99, 235, 0.28);
border-color: transparent;
color: rgba(255, 255, 255, 0.65);
}
/* 线框按钮：适合次级操作 */
QPushButton[tone="ghost"] {
background: transparent;
border-color: rgba(37, 99, 235, 0.55);
color: #2563eb;
}
/* 线框悬停：添加浅色背景提升悬停感受 */
QPushButton[tone="ghost"]:hover {
background-color: rgba(37, 99, 235, 0.12);
}
常见问题
  • macOS 原生风格会覆盖部分圆角和阴影，可在 main.cpp 中指定 QApplication::setStyle("fusion") 保持一致。
  • 若按钮位于 QToolBar，默认是 QToolButton 风格，需要单独匹配选择器。

1.3 QToolButton

结构亮点
  • 既可表现为普通按钮，也可展示下拉菜单、工具栏按钮。
  • 子控件：::menu-button（类似拆分按钮）、::menu-indicator、::popup。
  • 支持 ToolButtonTextUnderIcon、TextBesideIcon 等模式，可通过 toolButtonStyle 调整图文排布。
样式要点
选择器说明示例
QToolButton主体padding: 6px; border-radius: 6px;
QToolButton:hover悬停高亮background-color: rgba(37, 99, 235, 0.12);
QToolButton:pressed按下压感background-color: rgba(37, 99, 235, 0.18);
QToolButton:checked切换按钮激活状态background-color: rgba(37, 99, 235, 0.2);
QToolButton:disabled禁用态color: rgba(51, 65, 85, 0.45);
QToolButton[autoRaise="true"]工具栏扁平风格background: transparent; border: none;
QToolButton[popupMode="MenuButtonPopup"]拆分按钮整体padding-right: 22px;
QToolButton[popupMode="MenuButtonPopup"]::menu-button拆分按钮右半部分width: 16px; border-left: 1px solid rgba(37, 99, 235, 0.2);
QToolButton::menu-button:pressed菜单按钮按下反馈background: rgba(37, 99, 235, 0.24);
QToolButton::menu-indicator菜单箭头image: url(:/icons/chevron-down.svg);
QToolButton::menu-indicator:open菜单展开态image: url(:/icons/chevron-up.svg);
QToolButton::popup弹出菜单面板容器padding: 4px; border-radius: 8px;
/* 工具按钮主体：兼容工具栏与独立按钮 */
QToolButton {
/* 确保图标清晰 */
icon-size: 18px 18px;
/* 保持统一触控面积 */
padding: 6px;
border-radius: 6px;
background-color: transparent;
}
/* 悬停：给出浅色提示 */
QToolButton:hover {
background-color: rgba(37, 99, 235, 0.12);
}
/* 按下：色块稍加深 */
QToolButton:pressed {
background-color: rgba(37, 99, 235, 0.18);
}
/* 切换状态：保持高亮 */
QToolButton:checked {
background-color: rgba(37, 99, 235, 0.2);
border: 1px solid rgba(37, 99, 235, 0.25);
}
/* 禁用：整体降透明度 */
QToolButton:disabled {
background-color: transparent;
color: rgba(51, 65, 85, 0.45);
}
/* 拆分按钮的菜单区域：增加分隔线 */
QToolButton::menu-button {
border-left: 1px solid rgba(37, 99, 235, 0.2);
width: 16px;
background: transparent;
}
/* 菜单区域按下反馈 */
QToolButton::menu-button:pressed {
background: rgba(37, 99, 235, 0.24);
}
/* 下拉箭头使用统一资源 */
QToolButton::menu-indicator {
image: url(:/icons/chevron-down.svg);
}
/* 菜单展开后更换向上箭头，提示弹出状态 */
QToolButton::menu-indicator:open {
image: url(:/icons/chevron-up.svg);
}

1.4 QCommandLinkButton

  • 内置标题与描述两行文本，对应子控件 ::description。
  • 默认带箭头图标，可通过 icon 自定义或隐藏。
  • 支持 :hover、:pressed、:default、:disabled 状态。
关键属性
选择器/属性功能说明示例
QCommandLinkButton主按钮外观padding: 12px 18px; border-radius: 10px;
QCommandLinkButton:hover悬停态background-color: rgba(37,99,235,0.08);
QCommandLinkButton:pressed按压态background-color: rgba(37,99,235,0.14);
QCommandLinkButton:default默认按钮border-color: #2563eb;
QCommandLinkButton:disabled禁用态color: rgba(71,85,105,0.45);
QCommandLinkButton::description副标题文本font-size: 12px; color: rgba(...);
QCommandLinkButton::icon左侧图标image: url(:/icons/arrow-right.svg);
qproperty-description代码注入描述文本button->setProperty("description", ...)
qproperty-iconSize描述图标尺寸（Qt 6）qproperty-iconSize: QSize(32,32);
/* 命令链接按钮主体：大卡片+箭头风格 */
QCommandLinkButton {
padding: 12px 18px;
border-radius: 10px;
border: 1px solid rgba(148, 163, 184, 0.35);
color: #0f172a;
font-weight: 500;
}
/* 副标题：灰色小字号 */
QCommandLinkButton::description {
color: rgba(71, 85, 105, 0.85);
font-size: 12px;
margin-top: 4px;
}
/* 悬停：浅色底 */
QCommandLinkButton:hover {
background-color: rgba(37, 99, 235, 0.08);
}
/* 按下：略加深，营造点击反馈 */
QCommandLinkButton:pressed {
background-color: rgba(37, 99, 235, 0.14);
}
/* 禁用：主标题和副标题全部降透明度 */
QCommandLinkButton:disabled {
color: rgba(71, 85, 105, 0.45);
}

2. 切换控件（Checkable Controls）

2.1 QCheckBox

结构剖析
  • 主体：QCheckBox
  • 子控件：::indicator（复选框图标）、::indicator:unchecked、::indicator:checked、::indicator:indeterminate
  • 常见伪状态：:hover、:pressed、:disabled、:focus、:indicator:hover
关键属性
选择器功能取值示例提示
QCheckBox控制文字区域spacing: 8px; padding: 4px;spacing 控制文本与指示器间距
QCheckBox:focus键盘聚焦outline: none; + border可结合 :focus 自定义外框
QCheckBox:disabled禁用态color: rgba(71,85,105,0.45);同步调整指示器禁用配色
QCheckBox::indicator调整指示器尺寸width: 16px; height: 16px;需设定背景、边框或图片
QCheckBox::indicator:unchecked未勾选background: #fff;可定制为空心方框或浅灰底
QCheckBox::indicator:hover悬停态border-color: #2563eb;强调可勾选区域
QCheckBox::indicator:pressed按下态background-color: rgba(37,99,235,0.18);提供点击反馈
QCheckBox::indicator:checked渲染勾选状态image: url(:/icons/check.svg);图片需自带透明背景
QCheckBox::indicator:checked:disabled禁用勾选background-color: rgba(148,163,184,0.35);保持状态但弱化视觉权重
QCheckBox::indicator:indeterminate三态background-color: #2563eb;与 setTristate(true) 组合
实战：方形与圆形主题
/* 复选框主体：控制文本与指示器间距 */
QCheckBox {
/* 文本和勾选框之间的距离 */
spacing: 8px;
/* 统一字号 */
font-size: 14px;
}
/* 指示器：创建方形勾选框 */
QCheckBox::indicator {
/* 指示器尺寸 */
width: 18px;
height: 18px;
/* 圆角可调整为圆形复选框 */
border-radius: 4px;
/* 默认边框颜色 */
border: 1px solid rgba(71, 85, 105, 0.45);
/* 默认背景为白色 */
background-color: #fff;
}
/* 悬停时强调边框颜色 */
QCheckBox::indicator:hover {
border-color: #2563eb;
}
/* 勾选态：填充品牌色并绘制对勾 */
QCheckBox::indicator:checked {
border-color: #2563eb;
background-color: #2563eb;
image: url(:/icons/check-small.svg);
}
/* 三态：用于部分选中场景 */
QCheckBox::indicator:indeterminate {
border-color: #f59e0b;
background-color: #f59e0b;
image: url(:/icons/minus.svg);
}
进阶：自定义开关（Switch）
  • 利用 QCheckBox + 动态属性 appearance="switch"。
  • 使用 ::indicator 充当轨道，::indicator::checked 伪状态中通过 QBoxShadow 或背景渐变表达激活。
  • 通过 subcontrol-position 或伪元素自绘滑块。
QCheckBox[appearance="switch"] {
padding: 4px 0;
}
QCheckBox[appearance="switch"]::indicator {
width: 40px;
height: 20px;
border-radius: 10px;
border: 1px solid rgba(148, 163, 184, 0.45);
background-color: rgba(226, 232, 240, 0.9);
image: url(:/switch/knob-left.png);
}
QCheckBox[appearance="switch"]::indicator:hover {
border-color: rgba(37, 99, 235, 0.65);
}
QCheckBox[appearance="switch"]::indicator:checked {
border-color: #22c55e;
background-color: rgba(34, 197, 94, 0.35);
image: url(:/switch/knob-right.png);
}
QCheckBox[appearance="switch"]::indicator:disabled {
border-color: rgba(148, 163, 184, 0.25);
background-color: rgba(148, 163, 184, 0.15);
image: url(:/switch/knob-disabled.png);
}

若需无资源依赖的圆点动画，可在代码中组合 QStateMachine 或自绘；单纯使用 QSS 时，可利用两套 PNG/SVG 表现滑块位置，或改用自定义 QWidget。

2.2 QRadioButton

  • 与 QCheckBox 相似，但 ::indicator 通常为圆形。
  • 可通过 QButtonGroup 设置互斥。
QRadioButton::indicator {
width: 16px;
height: 16px;
border-radius: 8px;
border: 1px solid rgba(71, 85, 105, 0.45);
background-color: #fff;
}
QRadioButton::indicator:checked {
border-color: #2563eb;
background-color: #2563eb;
image: url(:/icons/radio-dot.svg);
}

3. 文本与表单输入控件

3.1 QLineEdit

结构剖析
  • 主体：QLineEdit
  • 子控件：::placeholder（Qt 5.12+），::clear-button（Qt 5.2+，启用 setClearButtonEnabled(true)）
  • 伪状态：:focus、:read-only、:disabled、:hover
关键属性
选择器功能示例小贴士
QLineEdit背景、边框、内边距padding: 6px 10px;保留足够空间容纳清除按钮
QLineEdit:hover悬停态border-color: rgba(37,99,235,0.45);用浅色边框暗示可编辑
QLineEdit:focus高亮状态border-color: #2563eb;可叠加 outline 提示键盘焦点
QLineEdit:read-only只读样式background-color: #f8fafc;通过颜色差异提示不可编辑
QLineEdit:disabled禁用样式color: rgba(71,85,105,0.45);同时调整边框与背景强调不可用
QLineEdit[echoMode="Password"]密码模式lineedit[echoMode="Password"] { letter-spacing: 2px; }通过字符间距增强可读性
QLineEdit[frame="false"]去除边框border: none;常与嵌套容器搭配自定义边框
QLineEdit::placeholder占位文本color: rgba(71,85,105,0.65);Qt 5.12 前需改用 setPlaceholderText + 样式表 trick
QLineEdit::selection选中文本background-color: rgba(37,99,235,0.2);可与 selection-color 搭配
QLineEdit::clear-button清除按钮image: url(:/icons/close-circle.svg);设置 subcontrol-position: right center; 调整位置
qproperty-alignment文本对齐`qproperty-alignment: AlignRightAlignVCenter;`做金额输入或右对齐时使用
qproperty-completer自动补全qproperty-completer: completerInstance;需在代码中设置对象名并注入
/* 输入框主体：基础边框与内边距 */
QLineEdit {
/* 留出文字和边框之间的空隙，同时预留清除按钮位置 */
padding: 6px 12px;
/* 默认描边，使用中性色 */
border: 1px solid rgba(148, 163, 184, 0.65);
/* 圆角让表单更友好 */
border-radius: 6px;
/* 背景设为白色，适合浅色主题 */
background-color: #ffffff;
/* 选中文本背景色，提升可见度 */
selection-background-color: rgba(37, 99, 235, 0.2);
}
/* 聚焦时高亮边框与背景 */
QLineEdit:focus {
border-color: #2563eb;
background-color: #f1f5ff;
}
/* 占位符颜色：较正文浅一档 */
QLineEdit::placeholder {
color: rgba(100, 116, 139, 0.7);
}
/* 清除按钮：统一图标和尺寸 */
QLineEdit::clear-button {
image: url(:/icons/close-circle.svg);
width: 16px;
height: 16px;
}

3.2 QTextEdit / QPlainTextEdit

  • 支持滚动条子控件 QScrollBar。需要单独样式。
  • QTextEdit 支持富文本，QPlainTextEdit 用于纯文本，QSS 入口基本一致。
  • 可使用 line-height（Qt 6.2+）调整行距。
关键属性
选择器/属性功能说明示例
QTextEdit / QPlainTextEdit主体外观、背景padding: 10px 12px; border-radius: 8px;
QTextEdit:hover悬停提示border-color: rgba(37,99,235,0.45);
QTextEdit:focus焦点状态border-color: #2563eb;
QTextEdit:read-only只读样式background-color: #f8fafc;
QTextEdit:disabled禁用态color: rgba(71,85,105,0.45);
QTextEdit::placeholder（Qt 6.2+）占位文本color: rgba(100,116,139,0.6);
QTextEdit::corner右下角占位部件background: transparent;
QTextEdit QScrollBar:vertical垂直滚动条轨道width: 8px; margin: 4px;
QTextEdit QScrollBar::handle:vertical垂直滚动条滑块background: rgba(148,163,184,0.65);
QTextEdit QScrollBar:horizontal水平滚动条height: 8px;
QPlainTextEdit[tabChangesFocus="true"]Tab 转换焦点的文本编辑器background-color: #ffffff;
qproperty-lineWrapMode控制换行模式（代码设置）editor->setLineWrapMode(QTextEdit::NoWrap);
qproperty-overwriteMode置换模式指示editor->setOverwriteMode(true);
/* 多行文本：保持和单行一致的设计语言 */
QTextEdit {
border: 1px solid rgba(148, 163, 184, 0.65);
border-radius: 8px;
/* 适当增大内边距，提升阅读体验 */
padding: 10px 12px;
background-color: #ffffff;
selection-background-color: rgba(37, 99, 235, 0.18);
}
/* 聚焦时同步高亮边框 */
QTextEdit:focus {
border-color: #2563eb;
background-color: #f8fbff;
}
/* 只读：背景变淡以示区分 */
QTextEdit:read-only {
background-color: rgba(241, 245, 249, 0.85);
}
/* 内部垂直滚动条：与整体主题一致 */
QTextEdit QScrollBar:vertical {
width: 8px;
margin: 4px;
background: transparent;
}
QTextEdit QScrollBar::handle:vertical {
min-height: 32px;
border-radius: 4px;
background-color: rgba(148, 163, 184, 0.65);
}
/* 水平滚动条同样跟随配色 */
QTextEdit QScrollBar:horizontal {
height: 8px;
margin: 0 4px;
background: transparent;
}
QTextEdit QScrollBar::handle:horizontal {
min-width: 32px;
border-radius: 4px;
background-color: rgba(148, 163, 184, 0.65);
}

3.3 QSpinBox / QDoubleSpinBox

  • 子控件：::up-button、::down-button、::up-arrow、::down-arrow。
  • 可通过 padding-right 留出按钮空间。
  • 支持 :up-button:pressed、:down-button:pressed、:disabled 等状态。
关键属性
选择器/属性功能说明示例
QSpinBox / QDoubleSpinBox主体外观padding: 4px 24px 4px 10px;
QSpinBox:hover悬停状态border-color: rgba(37,99,235,0.45);
QSpinBox:focus聚焦状态border-color: #2563eb;
QSpinBox:disabled禁用态color: rgba(71,85,105,0.45);
QSpinBox::up-button增量按钮容器width: 20px; subcontrol-position: top right;
QSpinBox::up-button:pressed增量按钮按下background: rgba(37,99,235,0.18);
QSpinBox::down-button减量按钮容器width: 20px; subcontrol-position: bottom right;
QSpinBox::down-button:pressed减量按钮按下background: rgba(37,99,235,0.18);
QSpinBox::up-arrow / ::down-arrow箭头图标image: url(:/icons/chevron-up.svg);
QSpinBox[buttonSymbols="NoButtons"]隐藏按钮（仅数值输入）border: 1px solid ...; padding-right: 10px;
QSpinBox::up-button:disabled禁用按钮background: transparent; image: none;
qproperty-prefix / qproperty-suffix前缀/后缀文本spin->setPrefix("￥");
/* 数值输入框：右侧预留增减按钮 */
QSpinBox {
/* padding-right 需要覆盖按钮宽度 */
padding: 4px 24px 4px 10px;
border: 1px solid rgba(148, 163, 184, 0.65);
border-radius: 6px;
background-color: #ffffff;
}
/* 聚焦态：描边改为品牌色 */
QSpinBox:focus {
border-color: #2563eb;
}
/* 上升按钮：位于右上角 */
QSpinBox::up-button {
subcontrol-origin: border;
subcontrol-position: top right;
width: 20px;
border-left: 1px solid rgba(148, 163, 184, 0.35);
background-color: rgba(148, 163, 184, 0.08);
}
/* 上箭头图标 */
QSpinBox::up-arrow {
image: url(:/icons/chevron-up.svg);
width: 10px;
height: 10px;
}
/* 下箭头图标 */
QSpinBox::down-arrow {
image: url(:/icons/chevron-down.svg);
width: 10px;
height: 10px;
}
/* 下降按钮：位于右下角 */
QSpinBox::down-button {
subcontrol-origin: border;
subcontrol-position: bottom right;
width: 20px;
border-left: 1px solid rgba(148, 163, 184, 0.35);
background-color: rgba(148, 163, 184, 0.08);
}
/* 按下时略加深背景 */
QSpinBox::up-button:pressed,
QSpinBox::down-button:pressed {
background-color: rgba(37, 99, 235, 0.18);
}
/* 禁用态隐藏箭头，使视觉统一 */
QSpinBox::up-arrow:disabled,
QSpinBox::down-arrow:disabled {
image: none;
}

3.4 QDateEdit / QTimeEdit / QDateTimeEdit

  • 派生自 QAbstractSpinBox，包含下拉日历。
  • 子控件 ::drop-down 控制下拉按钮，::down-arrow 控制箭头。
  • 下拉日历是 QCalendarWidget，需分别设置其子控件。
关键属性
选择器/属性功能说明示例
QDateEdit / QTimeEdit主体外观padding: 4px 28px 4px 10px; border-radius: 6px;
QDateEdit:focus聚焦态border-color: #2563eb;
QDateEdit:disabled禁用态color: rgba(71,85,105,0.45);
QDateEdit::drop-down下拉按钮区域width: 24px; border-left: 1px solid rgba(...);
QDateEdit::drop-down:pressed下拉按钮按压background: rgba(37,99,235,0.18);
QDateEdit::down-arrow箭头图标image: url(:/icons/calendar.svg);
QDateEdit[calendarPopup="true"]启用日历弹窗background-color: #ffffff;
QDateEdit::up-button / ::down-button时间编辑器增减按钮width: 18px; subcontrol-position: top right;
QCalendarWidget日历整体容器border-radius: 8px; padding: 12px;
QCalendarWidget QToolButton年/月切换按钮icon-size: 16px; border-radius: 6px;
QCalendarWidget QToolButton:pressed按压态background: rgba(37,99,235,0.18);
QCalendarWidget QAbstractItemView::item日期单元格min-height: 28px;
QCalendarWidget QAbstractItemView::item:hover悬停单元background: rgba(37,99,235,0.1);
QCalendarWidget QWidget#qt_calendar_navigationbar顶部导航栏background: rgba(148,163,184,0.12);
qproperty-displayFormat日期时间显示格式（代码）edit->setDisplayFormat("yyyy-MM-dd HH:mm");
/* 日期编辑器主体：右侧预留下拉按钮 */
QDateEdit {
padding: 4px 28px 4px 10px;
border: 1px solid rgba(148, 163, 184, 0.65);
border-radius: 6px;
background-color: #ffffff;
}
/* 焦点态：描边改为主色 */
QDateEdit:focus {
border-color: #2563eb;
}
/* 下拉按钮区域：分隔线 + 浅色底 */
QDateEdit::drop-down {
subcontrol-origin: padding;
subcontrol-position: right center;
width: 24px;
border-left: 1px solid rgba(148, 163, 184, 0.35);
background-color: rgba(148, 163, 184, 0.12);
}
/* 按下下拉按钮给出反馈 */
QDateEdit::drop-down:pressed {
background-color: rgba(37, 99, 235, 0.18);
}
/* 下拉箭头使用日历图标 */
QDateEdit::down-arrow {
image: url(:/icons/calendar.svg);
width: 12px;
height: 12px;
}
/* 日历部件：整体容器 */
QCalendarWidget {
background-color: #ffffff;
border: 1px solid rgba(148, 163, 184, 0.45);
border-radius: 8px;
padding: 12px;
}
/* 顶部导航条背景与按钮 */
QCalendarWidget QWidget#qt_calendar_navigationbar {
background-color: rgba(148, 163, 184, 0.12);
border-radius: 6px;
}
/* 顶部导航按钮（上一月/下一月） */
QCalendarWidget QToolButton {
icon-size: 16px;
border: none;
padding: 4px;
border-radius: 6px;
}
QCalendarWidget QToolButton:hover {
background-color: rgba(37, 99, 235, 0.12);
}
/* 日期单元格：选中高亮 */
QCalendarWidget QAbstractItemView:enabled {
selection-background-color: rgba(37, 99, 235, 0.2);
selection-color: #1d4ed8;
outline: none;
}
QCalendarWidget QAbstractItemView::item {
min-height: 28px;
margin: 2px 4px;
}
QCalendarWidget QAbstractItemView::item:hover {
background-color: rgba(37, 99, 235, 0.1);
}
/* 今日日期额外描边（保持非激活时的高亮） */
QCalendarWidget QTableView::item:selected:!active {
background-color: rgba(37, 99, 235, 0.18);
}

4. 下拉与选择器

4.1 QComboBox

结构剖析
  • 主体：QComboBox
  • 子控件：::drop-down（下拉按钮区域）、::down-arrow（箭头）、::indicator（可编辑模式下的下拉标记）、::item（Qt
    6 支持）
  • 弹出视图：QComboBox QAbstractItemView，通常为 QListView
属性对照
选择器功能示例说明
QComboBox控制外观padding: 4px 28px 4px 10px;需留出下拉按钮宽度
QComboBox:hover悬停态border-color: rgba(37,99,235,0.45);鼠标悬停时浅色描边
QComboBox:focus聚焦态border-color: #2563eb;支持键盘导航高亮
QComboBox:editable可编辑模式background: #ffffff;内含 QLineEdit，需同步样式
QComboBox::drop-down定义按钮区域width: 24px; border-left: 1px solid ...可设置背景、圆角
QComboBox::drop-down:pressed按下态background: rgba(37,99,235,0.18);显示交互反馈
QComboBox::down-arrow箭头图标image: url(:/icons/chevron-down.svg);可替换为自定义 SVG
QComboBox::indicator可编辑下拉指示image: url(:/icons/menu.svg);仅在 editable 模式可见
QComboBox:on下拉展开状态border-color: #2563eb;用于高亮展开中的控件
QComboBox::item（Qt 6）主题化弹出项padding: 6px 14px;直接在 QSS 控制列表项外观
QComboBox QListView::item列表项min-height: 28px;Qt 5 可通过视图类匹配
QComboBox QListView::item:selected选中项background: rgba(37,99,235,0.18);强调当前选项
QComboBox QAbstractItemView弹出列表border-radius: 8px;可统一滚动条、选中样式
QComboBox::separator分隔线height: 1px; background: rgba(148,163,184,0.35);需启用插入分隔符的模型
/* 下拉框主体：与输入框保持一致 */
QComboBox {
padding: 4px 28px 4px 10px;
border: 1px solid rgba(148, 163, 184, 0.65);
border-radius: 6px;
}
/* 右侧下拉按钮区：带分隔线和浅色背景 */
QComboBox::drop-down {
subcontrol-origin: padding;
subcontrol-position: right center;
width: 26px;
border-left: 1px solid rgba(148, 163, 184, 0.35);
background-color: rgba(148, 163, 184, 0.12);
}
/* 下拉箭头图标 */
QComboBox::down-arrow {
image: url(:/icons/chevron-down.svg);
width: 12px;
height: 12px;
}
/* 弹出视图：统一背景与选中状态 */
QComboBox QAbstractItemView {
padding: 4px 0;
border: 1px solid rgba(148, 163, 184, 0.45);
border-radius: 8px;
background-color: #ffffff;
selection-background-color: rgba(37, 99, 235, 0.12);
selection-color: #1d4ed8;
}

4.2 QFontComboBox

选择器/属性功能说明示例
QFontComboBox主体外观min-width: 200px;
QFontComboBox::drop-down下拉按钮与 4.1 节保持一致
QFontComboBox QListView::item字体项min-height: 28px; font-size: 14px;
QFontComboBox QListView::item:hover悬停项background-color: rgba(37,99,235,0.12);
QFontComboBox QListView::item:selected选中项background-color: rgba(37,99,235,0.18);
QFontComboBox[fontFilters~="MonospacedFonts"]过滤字体fontCombo->setFontFilters(QFontComboBox::MonospacedFonts);
qproperty-currentFont当前字体（代码设置）fontCombo->setCurrentFont(QFont("Fira Code"));

4.3 可编辑组合框

  • QComboBox 设置 setEditable(true) 后内部包含 QLineEdit，需同步设置。
选择器/属性功能说明示例
QComboBox:editable可编辑模式主体background: #ffffff;
QComboBox:editable:on展开时border-color: #2563eb;
QComboBox::drop-down:editable下拉按钮image: none;
QComboBox QLineEdit内部行编辑border: none; padding: 4px 6px;
QComboBox QLineEdit:focus内部聚焦border: none; background: transparent;
QComboBox::indicator指示图标（可选）image: url(:/icons/chevron-down.svg);
/* 可编辑模式下保持白色背景 */
QComboBox:editable {
background: #ffffff;
}
/* 可编辑时移除下拉按钮上的箭头，避免与输入重复 */
QComboBox::drop-down:editable {
image: none;
}
/* 内部 QLineEdit 去掉边框，继承外框样式 */
QComboBox QLineEdit {
border: none;
padding: 4px 6px;
}

5. 滑动与滚动控件

5.1 QSlider

  • 子控件：::groove（轨道）、::handle（滑块）、::add-page、::sub-page（水平/垂直）、::tick-position（刻度）
  • 伪状态：:hover、:pressed、:disabled
关键属性
选择器/属性功能说明示例
QSlider::groove:horizontal水平轨道height: 4px; border-radius: 2px;
QSlider::groove:vertical垂直轨道width: 4px; border-radius: 2px;
QSlider::sub-page已滑过区段background-color: #2563eb;
QSlider::add-page未滑过区段background-color: rgba(148,163,184,0.35);
QSlider::handle滑块width: 16px; border: 2px solid #2563eb;
QSlider::handle:hover滑块悬停border-color: #1d4ed8;
QSlider::handle:pressed滑块按压background-color: #2563eb; color: #fff;
QSlider:disabled禁用态opacity: 0.4;（Qt 6.6+）
QSlider::tick-position刻度条位置margin-top: 8px;
QSlider::handle:vertical垂直滑块尺寸width: 16px; height: 16px; margin: 0 -6px;
QSlider[orientation="Vertical"]纵向整体匹配min-height: 120px;
qproperty-pageStep / qproperty-singleStep步长（代码配置）slider->setPageStep(10);
/* 水平滑块轨道：灰色背景 */
QSlider::groove:horizontal {
height: 4px;
border-radius: 2px;
background-color: rgba(148, 163, 184, 0.35);
}
/* 已滑动部分：使用主色标记 */
QSlider::sub-page:horizontal {
background-color: #2563eb;
border-radius: 2px;
}
/* 滑块：白底+主色描边 */
QSlider::handle:horizontal {
width: 16px;
height: 16px;
/* margin 调整滑块上下对齐 */
margin: -6px 0;
border-radius: 8px;
background-color: #ffffff;
border: 2px solid #2563eb;
}
/* 悬停时强化描边颜色 */
QSlider::handle:horizontal:hover {
border-color: #1d4ed8;
}
/* 按下时填充主色，模拟圆点按压效果 */
QSlider::handle:horizontal:pressed {
background-color: #2563eb;
color: #ffffff;
}
/* 垂直滑块：同样的视觉语言 */
QSlider::groove:vertical {
width: 4px;
border-radius: 2px;
background-color: rgba(148, 163, 184, 0.35);
}
QSlider::sub-page:vertical {
background-color: #2563eb;
border-radius: 2px;
}
QSlider::handle:vertical {
width: 16px;
height: 16px;
margin: 0 -6px;
border-radius: 8px;
background-color: #ffffff;
border: 2px solid #2563eb;
}

5.2 QScrollBar

  • 子控件：::handle、::add-line、::sub-line、::add-page、::sub-page、::corner
  • 可通过 qproperty-pageStep 控制滚动幅度（代码层）。
关键属性
选择器/属性功能说明示例
QScrollBar:vertical垂直轨道width: 8px; margin: 4px;
QScrollBar:horizontal水平轨道height: 8px; margin: 4px;
QScrollBar::handle滑块min-height: 32px; border-radius: 4px;
QScrollBar::handle:hover悬停background-color: rgba(37,99,235,0.65);
QScrollBar::handle:pressed按压background-color: rgba(37,99,235,0.85);
QScrollBar::add-line / ::sub-line顶/底按钮（分页按钮）height: 0; 或设置箭头图标
QScrollBar::add-page / ::sub-page未占用区域background: transparent;
QScrollBar::up-arrow / ::down-arrow箭头图标image: url(:/icons/chevron-up.svg);
QScrollBar::corner滚动条与滚动条交叉区域background: rgba(148,163,184,0.12);
QScrollBar:disabled禁用态background: transparent;
QScrollArea QWidget::viewport配合滚动区域背景background-color: #ffffff;
qproperty-singleStep单次滚动步长（代码）scrollBar->setSingleStep(24);
/* 垂直滚动条轨道 */
QScrollBar:vertical {
width: 8px;
background: transparent;
margin: 4px;
}
/* 滚动条滑块：默认灰色 */
QScrollBar::handle:vertical {
min-height: 32px;
border-radius: 4px;
background-color: rgba(148, 163, 184, 0.65);
}
/* 悬停时加深颜色提升可见度 */
QScrollBar::handle:vertical:hover {
background-color: rgba(37, 99, 235, 0.65);
}
/* 顶部/底部按钮隐藏（高度为 0） */
QScrollBar::add-line:vertical,
QScrollBar::sub-line:vertical {
height: 0px;
}
/* 轨道剩余部分保持透明 */
QScrollBar::add-page:vertical,
QScrollBar::sub-page:vertical {
background: transparent;
}
/* 水平滚动条保持同样视觉语言 */
QScrollBar:horizontal {
height: 8px;
background: transparent;
margin: 0 4px;
}
QScrollBar::handle:horizontal {
min-width: 32px;
border-radius: 4px;
background-color: rgba(148, 163, 184, 0.65);
}
QScrollBar::handle:horizontal:hover {
background-color: rgba(37, 99, 235, 0.65);
}
/* 交叉区域（如滚动条相交时） */
QScrollBar::corner {
background: rgba(148, 163, 184, 0.12);
}

5.3 QDial

  • 支持 background、foreground、notch 颜色，QSS 能力有限。
  • 高级样式建议使用 QProxyStyle 或自绘。
可用属性速查
选择器/属性功能说明示例
QDial背景与外框background: #ffffff; border-radius: 50%;
QDial::handle指针/旋钮（Qt 6+）image: url(:/dial/handle.svg);
QDial::notch刻度线颜色color: rgba(148,163,184,0.75);
QDial:focus聚焦态border: 2px solid #2563eb;
QDial:disabled禁用态透明度opacity: 0.4;（Qt 6.6+）
qproperty-notchTarget刻度数量（代码设置）dial->setNotchTarget(36);
qproperty-wrapping是否允许循环（代码）dial->setWrapping(true);

6. 进度与状态反馈

6.1 QProgressBar

  • 子控件：::chunk 表示完成部分。
  • 支持水平、垂直、文本位置 (text-visible 属性)。
关键属性
选择器/属性功能说明示例
QProgressBar主体容器min-height: 12px; text-align: center;
QProgressBar::chunk完成区块background: qlineargradient(...);
QProgressBar::chunk:indeterminate不确定状态动画（手动模拟）background: url(:/patterns/stripe.png) repeat;
QProgressBar[textVisible="false"]隐藏文本padding: 0;
QProgressBar[orientation="Vertical"]垂直进度条min-width: 12px;
QProgressBar::chunk:disabled禁用态区块background-color: rgba(148,163,184,0.35);
QProgressBar[format="%p%"]百分比格式（代码配置）progress->setFormat("%p% 已完成");
QProgressBar::chunk:vertical垂直区块width: 100%; margin: 0;
QProgressBar::chunk:horizontal水平区块height: 100%; margin: 0;
QProgressBar[textDirection="BottomToTop"]文本方向（代码）progress->setTextDirection(QProgressBar::BottomToTop);
/* 进度条外框 */
QProgressBar {
min-height: 12px;
border-radius: 6px;
background-color: rgba(148, 163, 184, 0.25);
text-align: center;
color: #1f2937;
font: 500 12px "Microsoft YaHei";
}
/* 已完成的进度块：渐变填充 */
QProgressBar::chunk {
border-radius: 6px;
background: qlineargradient(
x1: 0,
y1: 0,
x2: 1,
y2: 0,
stop: 0 #2563eb,
stop: 1 #60a5fa
);
}
/* 条纹样式示例：使用平铺图片 */
QProgressBar[chunkShape="striped"]::chunk {
background: url(:/patterns/stripe.png) repeat;
}
/* 垂直方向的进度条 */
QProgressBar[orientation="Vertical"] {
min-width: 12px;
min-height: 120px;
}
QProgressBar[orientation="Vertical"]::chunk {
width: 100%;
}

6.2 QProgressDialog

  • 聚合进度条与文本，主体为 QDialog。
  • 可针对 QProgressDialog QLabel、QProgressDialog QPushButton、内部 QProgressBar 分别设置。
选择器/属性功能说明示例
QProgressDialog对话框外框border-radius: 12px; background: #ffffff;
QProgressDialog > QLabel文本区域font-size: 14px; color: #0f172a;
QProgressDialog > QPushButton取消按钮min-width: 88px;
QProgressDialog QProgressBar嵌入进度条与 6.1 节保持一致
QProgressDialog[minimumDuration=0]秒显模式（代码）dialog->setMinimumDuration(0);
QProgressDialog[autoClose="false"]禁止自动关闭（代码）dialog->setAutoClose(false);

6.3 状态指示类控件

  • QLCDNumber：可通过 color、background-color、segment-style 控制外观。
  • QStatusBar 消息提示参见第 9 节。

7. 视图、表格与表头

7.1 QListView / QTreeView

  • 子控件：::item、::branch（QTreeView）
  • 支持 alternate-background-color、:selected、:hover、:disabled
关键属性
选择器/属性功能说明示例
QListView / QTreeView主体容器border-radius: 8px; padding: 4px 0;
QListView::item列表项基础样式min-height: 32px; padding: 0 14px;
QListView::item:hover悬停态background-color: rgba(37,99,235,0.1);
QListView::item:selected选中态background-color: rgba(37,99,235,0.22);
QListView::item:selected:!active非活跃窗口选中background-color: rgba(37,99,235,0.12);
QTreeView::branch树枝节点image: url(:/icons/tree-closed.svg);
QTreeView::branch:open展开状态图标image: url(:/icons/tree-open.svg);
QTreeView::branch:has-siblings:adjoins-item多子节点缩进border-image: none;
QTreeView::indicator（可选）勾选框（若可选）width: 14px; height: 14px;
QTreeView::item:selected:focus焦点与选中outline: none;
QListView::indicator（带复选模型时）自定义复选框image: url(:/icons/check.svg);
qproperty-uniformRowHeights优化树视图性能（代码）tree->setUniformRowHeights(true);
/* 列表视图容器：白底+圆角 */
QListView {
border: 1px solid rgba(148, 163, 184, 0.45);
border-radius: 8px;
background-color: #ffffff;
padding: 4px 0;
}
/* 单行项：保证留白 */
QListView::item {
min-height: 32px;
padding: 0 14px;
}
/* 悬停高亮 */
QListView::item:hover {
background-color: rgba(37, 99, 235, 0.1);
}
/* 选中项：填充品牌色并改变文字颜色 */
QListView::item:selected {
background-color: rgba(37, 99, 235, 0.22);
color: #1d4ed8;
}
/* 非激活窗口中的选中项：保持可见但降低饱和度 */
QListView::item:selected:!active {
background-color: rgba(37, 99, 235, 0.12);
color: #334155;
}
/* 树形控件枝节点：替换展开/折叠图标 */
QTreeView::branch:has-children:!has-siblings:closed,
QTreeView::branch:closed:has-children:has-siblings {
image: url(:/icons/tree-closed.svg);
}
QTreeView::branch:open:has-children {
image: url(:/icons/tree-open.svg);
}
/* 树节点项选中高亮与列表一致 */
QTreeView::item:selected {
background-color: rgba(37, 99, 235, 0.22);
color: #1d4ed8;
}

7.2 QTableView / QTableWidget

  • 子控件：水平/垂直表头 QHeaderView::section，交替行 alternate-background-color
  • 单元格使用 ::item，支持 :selected、:focus、:hover
关键属性
选择器/属性功能说明示例
QTableView表格主体gridline-color: rgba(148,163,184,0.35);
QTableView::item单元格样式padding: 6px 12px;
QTableView::item:selected选中单元background-color: rgba(37,99,235,0.18);
QTableView::item:focus焦点单元outline: 1px solid #2563eb;
QTableView::item:selected:!active非激活窗口选中background-color: rgba(37,99,235,0.12);
QHeaderView表头容器background-color: #f1f5f9;
QHeaderView::section表头单元padding: 8px 12px; border-right: 1px solid rgba(...);
QHeaderView::section:hover悬停表头background-color: rgba(148,163,184,0.18);
QHeaderView::section:checked勾选表头（列选择）background-color: rgba(37,99,235,0.18);
QHeaderView::up-arrow / ::down-arrow排序箭头image: url(:/icons/arrow-up.svg);
QTableCornerButton::section左上角按钮background: #f1f5f9; border: none;
QTableView QTableCornerButton::section:pressed按下角按钮background-color: rgba(37,99,235,0.18);
qproperty-wordWrap单元格换行（代码配置）table->setWordWrap(false);
/* 表格主体：设置网格线和交替行底色 */
QTableView {
gridline-color: rgba(148, 163, 184, 0.35);
border: 1px solid rgba(148, 163, 184, 0.45);
selection-background-color: rgba(37, 99, 235, 0.18);
selection-color: #1d4ed8;
alternate-background-color: #f8fafc;
}
/* 非激活窗口选中的项：降一点饱和度 */
QTableView::item:selected:!active {
background-color: rgba(37, 99, 235, 0.12);
}
/* 表头背景 */
QHeaderView {
background-color: #f1f5f9;
}
/* 表头单元：内边距与分隔线 */
QHeaderView::section {
padding: 8px 12px;
border: none;
border-right: 1px solid rgba(148, 163, 184, 0.45);
font-weight: 600;
}
QHeaderView::section:hover {
background-color: rgba(148, 163, 184, 0.18);
}
/* 选中表头（列选择） */
QHeaderView::section:checked {
background-color: rgba(37, 99, 235, 0.18);
}
/* 排序箭头使用统一图标 */
QHeaderView::up-arrow {
image: url(:/icons/chevron-up.svg);
}
QHeaderView::down-arrow {
image: url(:/icons/chevron-down.svg);
}
/* 左上角按钮与表头保持一致 */
QTableCornerButton::section {
background-color: #f1f5f9;
border: none;
}

7.3 QHeaderView

  • 支持 ::up-arrow、::down-arrow（排序指示）、:checked（列选择）。
  • QHeaderView::section 可设置 margin 控制勾选框位置。

8. 容器与结构控件

8.1 QGroupBox

  • 子控件：::title、::indicator（用于可折叠组）
  • 常用属性：title 位置（subcontrol-position: top left;）
选择器/属性功能说明示例
QGroupBox主容器border-radius: 10px; padding: 16px 20px 12px;
QGroupBox:hover悬停提示border-color: rgba(37,99,235,0.35);
QGroupBox[flat="true"]扁平组（无边框）border: none; margin-top: 0;
QGroupBox::title标题文本区域padding: 0 12px; subcontrol-position: top left;
QGroupBox::title:checked勾选标题color: #2563eb;
QGroupBox[checkable="true"]::indicator勾选框尺寸与样式width: 16px; height: 16px;
QGroupBox::indicator:checked勾选后状态image: url(:/icons/check.svg);
QGroupBox::indicator:hover勾选悬停border-color: #2563eb;
QGroupBox::indicator:disabled禁用勾选background-color: rgba(148,163,184,0.25);
QGroupBox > QWidget内部直接子控件可额外设置 margin-top 以避免标题覆盖
/* GroupBox 边框与内边距 */
QGroupBox {
border: 1px solid rgba(148, 163, 184, 0.35);
border-radius: 10px;
margin-top: 16px;
padding: 16px 20px 12px;
}
/* 标题区域：通过 subcontrol 定位 */
QGroupBox::title {
subcontrol-origin: margin;
subcontrol-position: top left;
padding: 0 12px;
font-weight: 600;
color: #1f2937;
background-color: #f8fafc;
border-radius: 12px;
}
/* 可勾选组的指示器尺寸 */
QGroupBox[checkable="true"]::indicator {
width: 16px;
height: 16px;
}
QGroupBox[checkable="true"]::indicator:checked {
border: 1px solid #2563eb;
background-color: #2563eb;
image: url(:/icons/check-small.svg);
}
QGroupBox[checkable="true"]::indicator:hover {
border-color: #2563eb;
}

8.2 QFrame

  • 用于分割线、卡片容器。
  • 常见 frameShape：HLine、VLine，可通过 QSS 设置 border、background-color。
选择器/属性功能说明示例
QFrame基础外观border: 1px solid rgba(148,163,184,0.35);
QFrame[frameShape="NoFrame"]无边框容器border: none;
QFrame[frameShape="Box"]盒式边框border: 1px solid rgba(15,23,42,0.12);
QFrame[frameShape="StyledPanel"]面板风格border-radius: 12px; background: #ffffff;
QFrame[frameShape="HLine"]水平分割线max-height: 1px; background: rgba(...);
QFrame[frameShape="VLine"]垂直分割线max-width: 1px; background: rgba(...);
QFrame[frameShadow="Raised"]凸起阴影（代码控制）需配合 setFrameShadow 使用
qproperty-lineWidth边框宽度frame->setLineWidth(2);

8.3 QTabWidget

  • 组成：::pane（内容区域）、::tab-bar、QTabBar::tab、QTabBar::close-button
  • 伪状态：:selected、:hover、:!selected、:first、:last
选择器/属性功能说明示例
QTabWidget::pane内容区域外框border: 1px solid rgba(148,163,184,0.45);
QTabWidget::tab-bar标签条容器left: 0px; alignment: center;
QTabBar::tab普通标签padding: 8px 18px; border-top-left-radius: 8px;
QTabBar::tab:selected选中标签background: #ffffff; border-bottom-color: transparent;
QTabBar::tab:!selected:hover未选中悬停color: #2563eb;
QTabBar::tab:first / ::tab:last首末标签margin-left/right: 0;
QTabBar::tab:disabled禁用标签color: rgba(51,65,85,0.45);
QTabBar::close-button关闭按钮subcontrol-position: right; image: url(:/icons/close.svg);
QTabBar::close-button:hover关闭按钮悬停background: rgba(248,113,113,0.18);
QTabBar::tear分离器样式（可拖离）image: none;（隐藏默认撕裂条）
QTabWidget::pane:top / :bottom不同位置的 pane 边界修正border-top: none; 等
qproperty-documentMode文档模式（代码配置）tabWidget->setDocumentMode(true);
/* 标签页外框（内容区域边框） */
QTabWidget::pane {
border: 1px solid rgba(148, 163, 184, 0.45);
border-radius: 10px;
background-color: #ffffff;
}
/* 普通标签：圆角 + 浅色底 */
QTabBar::tab {
padding: 8px 18px;
margin-right: 4px;
border-top-left-radius: 8px;
border-top-right-radius: 8px;
background-color: rgba(148, 163, 184, 0.12);
color: #334155;
}
/* 选中标签：顶边连接 pane，底边去掉 */
QTabBar::tab:selected {
background-color: #ffffff;
color: #2563eb;
border: 1px solid rgba(148, 163, 184, 0.45);
border-bottom-color: transparent;
}
/* 未选中悬停：仅修改文字颜色 */
QTabBar::tab:!selected:hover {
color: #2563eb;
}
/* 文档模式：标签贴合内容区域 */
QTabWidget[documentMode="true"]::pane {
border: none;
}
/* 关闭按钮统一风格 */
QTabBar::close-button {
subcontrol-position: right;
image: url(:/icons/close.svg);
margin-left: 8px;
}
QTabBar::close-button:hover {
background-color: rgba(248, 113, 113, 0.18);
border-radius: 4px;
}

8.4 QScrollArea

  • 主要通过内部 viewport 和滚动条自定义。
  • 在 QSS 中使用 QScrollArea > QWidget 选择器可针对内容区设置背景。
选择器/属性功能说明示例
QScrollArea外框/边界border: none; background: transparent;
QScrollArea > QWidget > QWidget实际内容容器background: #ffffff;
QScrollArea QWidget子控件通用设置border: none;
QScrollArea::corner滚动条交叉区域background: rgba(148,163,184,0.12);
QScrollArea[frameShape="NoFrame"]取消边框border: none;
QScrollArea[widgetResizable="true"]自动拉伸内容（代码）scroll->setWidgetResizable(true);
QScrollArea:disabled禁用态background: rgba(148,163,184,0.08);
qproperty-alignment内容对齐（代码配置）scroll->setAlignment(Qt::AlignCenter);
/* ScrollArea 外框默认透明 */
QScrollArea {
border: none;
background: transparent;
}
/* 内容容器：去掉背景，交由子控件控制 */
QScrollArea > QWidget > QWidget {
background: transparent;
}
/* 内部子控件默认不绘制边框 */
QScrollArea QWidget {
border: none;
}
/* 交叉区域默认与滚动条一致 */
QScrollArea::corner {
background-color: rgba(148, 163, 184, 0.12);
}

9. 菜单、工具栏与状态栏

9.1 QMenuBar

  • 子控件：::item
  • 伪状态：:selected、:pressed
选择器/属性功能说明示例
QMenuBar主体背景background-color: #ffffff;
QMenuBar::item菜单项padding: 6px 12px; border-radius: 6px;
QMenuBar::item:selected悬停/激活项background-color: rgba(37,99,235,0.12);
QMenuBar::item:pressed按压态background-color: rgba(37,99,235,0.18);
QMenuBar::item:disabled禁用菜单项color: rgba(51,65,85,0.45);
QMenuBar::separator分割线（Qt 6+）width: 1px; background: rgba(148,163,184,0.35);
QMenuBar QMenu下拉菜单继承 9.2 节设置
qproperty-nativeMenuBar是否使用原生菜单menuBar->setNativeMenuBar(false);
QMenuBar {
background-color: #ffffff;
border-bottom: 1px solid rgba(148, 163, 184, 0.28);
}
QMenuBar::item {
padding: 6px 12px;
margin: 0 4px;
border-radius: 6px;
}
QMenuBar::item:selected {
background-color: rgba(37, 99, 235, 0.12);
color: #2563eb;
}
QMenuBar::item:pressed {
background-color: rgba(37, 99, 235, 0.18);
}

9.2 QMenu

  • 子控件：::item、::separator、::indicator（复选/单选菜单项）、::icon
  • 提示：可使用 menu->setWindowFlags(menu->windowFlags() | Qt::FramelessWindowHint); + QSS 自定义阴影。
选择器/属性功能说明示例
QMenu菜单面板border-radius: 10px; padding: 6px 0;
QMenu::item菜单项padding: 6px 18px; border-radius: 6px;
QMenu::item:selected悬停/选中项background-color: rgba(37,99,235,0.12);
QMenu::item:disabled禁用项color: rgba(51,65,85,0.45);
QMenu::separator分割线height: 1px; background: rgba(148,163,184,0.35);
QMenu::indicator复选/单选标记width: 14px; image: url(:/icons/check.svg);
QMenu::icon左侧图标区域padding-right: 8px;
QMenu[tearoffEnabled="true"]撕裂菜单（Qt 支持）menu->setTearOffEnabled(true);
QMenu::right-arrow子菜单箭头image: url(:/icons/chevron-right.svg);
QMenu::item:checked勾选状态background-color: rgba(37,99,235,0.18);
QMenu {
background-color: #ffffff;
border: 1px solid rgba(15, 23, 42, 0.12);
border-radius: 10px;
padding: 6px 0;
}
QMenu::item {
padding: 6px 18px;
border-radius: 6px;
}
QMenu::item:selected {
background-color: rgba(37, 99, 235, 0.12);
color: #2563eb;
}
QMenu::separator {
height: 1px;
margin: 6px 0;
background-color: rgba(148, 163, 184, 0.35);
}
QMenu::indicator:checked {
image: url(:/icons/check.svg);
}
QMenu::right-arrow {
image: url(:/icons/chevron-right.svg);
}
QMenu::icon {
padding-right: 8px;
}

9.3 QToolBar

  • 内部通常使用 QToolButton，可针对 QToolBar 设置背景、边框，并定制 ::separator。
选择器/属性功能说明示例
QToolBar工具栏主体background-color: rgba(248,250,252,0.9);
QToolBar::separator分隔线width: 1px; background-color: rgba(...);
QToolBar::handle拖动手柄image: url(:/icons/drag-dots.svg);
QToolBar::content（Qt 6+）内容区域padding: 0 6px;
QToolBar[floatable="true"]浮动工具栏border: 1px solid rgba(15,23,42,0.15);
QToolBar[orientation="Qt::Vertical"]垂直工具栏min-width: 40px;
QToolBar QWidget内部按钮统一配套 1.3 节 QToolButton
qproperty-movable是否可拖拽（代码配置）toolBar->setMovable(true);
QToolBar {
background-color: rgba(248, 250, 252, 0.9);
border-bottom: 1px solid rgba(148, 163, 184, 0.28);
spacing: 6px;
padding: 6px 8px;
}
QToolBar::separator {
width: 1px;
background-color: rgba(148, 163, 184, 0.45);
margin: 4px 10px;
}
QToolBar::handle {
image: url(:/icons/drag-dots.svg);
margin: 0 6px;
}

9.4 QStatusBar

  • 子控件：::item
  • 可设置固定高度、背景色，使用 addPermanentWidget() 的控件需要单独样式。
选择器/属性功能说明示例
QStatusBar状态栏主体background-color: #f1f5f9; border-top: 1px solid rgba(...);
QStatusBar::item临时消息项margin: 0 8px;
QStatusBar QLabel文本控件color: #475569;
QStatusBar QWidget[permanent="true"]常驻控件（动态属性）在代码中为常驻控件设置属性后可单独匹配
QStatusBar::item:message（Qt 6+）默认消息标签font-weight: 500;
qproperty-sizeGripEnabled是否显示尺寸拖拽控件statusBar->setSizeGripEnabled(false);
QStatusBar {
background-color: #f1f5f9;
border-top: 1px solid rgba(148, 163, 184, 0.28);
font-size: 12px;
}
QStatusBar::item {
border: none;
margin: 0 8px;
}
QStatusBar QLabel {
color: #475569;
}
/* 若在代码中为常驻控件设置 permanent 属性，可单独样式 */
QStatusBar QLabel[permanent="true"] {
margin-left: 16px;
font-weight: 500;
}
/* 尺寸拖拽控件（右下角），可统一颜色 */
QStatusBar QWidget#qt_sizegrip {
width: 12px;
height: 12px;
background: transparent;
}

10. 对话框、提示与辅助控件

10.1 QDialog / QMessageBox

  • QDialog 本身可通过 QDialog 选择器设置背景、圆角、阴影（结合 WA_TranslucentBackground）。
  • QMessageBox 子控件：::label、::icon、::button
选择器/属性功能说明示例
QDialog对话框主体border-radius: 14px; background: #ffffff;
QDialog[modal="true"]模态对话框border: 1px solid rgba(15,23,42,0.12);
QMessageBox消息框主体padding: 18px 24px; border-radius: 12px;
QMessageBox QLabel文本font-size: 14px; color: #0f172a;
QMessageBox QLabel#qt_msgbox_label主信息标签font-weight: 500;
QMessageBox QLabel#qt_msgboxex_icon_label图标min-width: 32px;
QMessageBox QPushButton按钮min-width: 88px; border-radius: 8px;
QMessageBox QPushButton:hover按钮悬停background-color: rgba(37,99,235,0.12);
QMessageBox QPushButton:default默认按钮background-color: #2563eb; color: #ffffff;
QMessageBox QPushButton:disabled禁用按钮color: rgba(71,85,105,0.45);
qproperty-modal模态开关（代码设置）dialog->setModal(true);
qproperty-windowTitle窗口标题（代码设置）dialog->setWindowTitle("提示");
QDialog {
background-color: #ffffff;
border-radius: 14px;
border: 1px solid rgba(15, 23, 42, 0.08);
}
QMessageBox {
background-color: #ffffff;
border-radius: 12px;
padding: 18px 24px;
}
QMessageBox QLabel {
color: #0f172a;
font-size: 14px;
}
QMessageBox QPushButton {
min-width: 88px;
padding: 6px 14px;
border-radius: 8px;
border: 1px solid rgba(148, 163, 184, 0.45);
}
QMessageBox QPushButton:hover {
background-color: rgba(37, 99, 235, 0.1);
}
QMessageBox QPushButton:default {
background-color: #2563eb;
border-color: #2563eb;
color: #ffffff;
}
QMessageBox QPushButton:disabled {
background-color: rgba(148, 163, 184, 0.12);
border-color: rgba(148, 163, 184, 0.12);
color: rgba(71, 85, 105, 0.45);
}

10.2 QDialogButtonBox

  • 聚合多个按钮，根据 ButtonRole 自动布局。
  • 可通过 QDialogButtonBox QPushButton[role="AcceptRole"] 匹配按钮角色。
选择器/属性功能说明示例
QDialogButtonBox按钮盒容器padding-top: 12px; background: transparent;
QDialogButtonBox QPushButton[role="AcceptRole"]接受按钮background: #16a34a; color: #ffffff;
QDialogButtonBox QPushButton[role="RejectRole"]拒绝按钮background: #ef4444; color: #ffffff;
QDialogButtonBox QPushButton[role="DestructiveRole"]危险操作background: #dc2626;
QDialogButtonBox QPushButton[role="HelpRole"]帮助按钮background: transparent; color: #2563eb;
QDialogButtonBox QPushButton:default默认按钮border: 1px solid #2563eb;
qproperty-centerButtons（Qt 6+）是否居中按钮box->setCenterButtons(true);
qproperty-standardButtons标准按钮集合（代码）`box->setStandardButtons(QDialogButtonBox::Ok…)`
QDialogButtonBox {
button-layout: 1; /* Qt 6+ 可控制排序 */
background: transparent;
padding-top: 12px;
}
QDialogButtonBox QPushButton[role="AcceptRole"] {
background-color: #16a34a;
color: #ffffff;
}
QDialogButtonBox QPushButton[role="RejectRole"] {
background-color: #ef4444;
color: #ffffff;
}
/* 提示按钮保持线框 */
QDialogButtonBox QPushButton[role="HelpRole"] {
background: transparent;
border: 1px solid rgba(37, 99, 235, 0.4);
color: #2563eb;
}

10.3 QToolTip / QWhatsThis

  • 系统默认字体与背景可通过 QSS 改写。
选择器/属性功能说明示例
QToolTip工具提示主体background-color: rgba(15,23,42,0.85);
QToolTip + font提示字体font: 400 12px "Microsoft YaHei";
QWhatsThis帮助提示窗口padding: 10px; border-radius: 8px;
QWhatsThis QTextBrowser帮助内容区font-size: 13px;
qproperty-toolTipDuration显示时长widget->setToolTipDuration(3000);
QToolTip {
background-color: rgba(15, 23, 42, 0.85);
color: #f8fafc;
border: 1px solid rgba(15, 23, 42, 0.45);
border-radius: 6px;
padding: 6px 8px;
font: 400 12px "Microsoft YaHei";
}

10.4 QStatusTipEvent

  • 状态栏提示可通过 QStatusBar 样式覆盖；若需要自定义浮层，可结合自定义 QWidget。

附录 A：常用选择器速查

控件关键选择器说明
QPushButton:default、::menu-indicator主按钮、菜单按钮
QCheckBox::indicator、:indeterminate复选框状态
QComboBox::drop-down、QAbstractItemView下拉按钮与弹出列表
QSlider::groove、::handle滑块轨道与句柄
QProgressBar::chunk进度条填充
QTableViewQHeaderView::section表头
QTabWidgetQTabBar::tab、::pane标签页
QMenu::item、::separator菜单项、分隔线

附录 B：调试建议

  1. 临时描边法：给 * { outline: 1px solid rgba(255,0,0,0.35); } 便于识别子控件。
  2. 分层加载：按模块拆分 .qss，最终汇总，避免单文件过大。
  3. 跨平台校验：在目标平台（Win/macOS/Linux）逐个验证控件是否遵循样式，必要时使用 QProxyStyle 修正。
  4. 资源管理：将常用 SVG/PNG 放入 Qt Resource（.qrc）统一管理，便于 url(:/res) 调用。
  5. 版本判断：对于 Qt 6 特性（如 ::icon、opacity 属性），使用 #if QT_VERSION >= QT_VERSION_CHECK(6, 2, 0) 条件编译保证兼容。

通过以上控件特性指南，可在通用属性主题的基础上，为不同交互控件快速制定一致又细腻的视觉规范。后续可进一步补充团队自定义控件或第三方控件的
QSS 入口，以形成完整的 UI 设计体系文档。