QT中QSS样式表的详细介绍

转自个人博客

**Qt样式表（Qt Style Sheets，简称QSS）**是一种类似于HTML中的CSS（层叠样式表）的机制，用于自定义Qt应用程序的外观。通过QSS，开发者可以轻松地修改控件的外观，而无需更改底层代码逻辑。这种方式不仅提高了开发效率，还增强了界面设计的灵活性。

---

1. QSS概要

1.1 QSS作用

QSS允许开发者通过声明式的方式设置控件的外观属性，例如颜色、字体、边框、间距等。与直接在代码中设置样式相比，QSS具有以下优点：

• 分离样式与逻辑：样式和功能代码分离，便于维护。
• 动态切换主题：可以通过加载不同的QSS文件实现主题切换。
• 跨平台一致性：确保不同平台上的控件外观一致。

1.2 QSS与CSS的关系

QSS借鉴了CSS的设计思想，语法上非常相似。熟悉CSS的开发者可以快速上手QSS。然而，QSS是专门为Qt控件设计的，因此支持的属性和选择器可能与CSS有所不同。

1.3 QSS基本语法

QSS的基本语法如下：

选择器 {属性: 值;
}

• 选择器：用于指定要应用样式的控件或控件组，支持多种类型的选择器来具体选择应用样式的对象。
• 属性：控件的外观属性。
• 值：属性的具体取值，不同的属性可能需要使用不同的值。

QPushButton {color: white;background-color: blue;border: 1px solid black;
}

1.4 QSS在QT中的使用

1. 可以在Qt Designer中直接键入样式表

2. 在Qt中对指定控件使用setStyleSheet(样式表字符串)方法设置。

   • 参数是字符串类型，引号内使用QSS语法，如果多行书写，也要记得将每一行套用双引号来转化成一个字符串。
   • 样式表是默认递归套用到子控件的，如果只想套用到指定的控件，就需要细分选择选择器。
   • 对一个控件不支持重复设置样式表，只有最后一个设置的样式表生效。但可以分别对父控件和子控件设置不同样式表，默认子控件样式在父控件之上生效。
   • 因为这种方法是直接对控件设置样式表，所以也支持省略选择器，以自动套用当前控件类型。

   // 对整个控件如下应用样式表会套用到所有子控件QPushButton上
   auto myWidget = new QWidget();
   myWidget->setStyleSheet("QPushButton { background-color: yellow }"); 
   // 多行书写需要每一行使用双引号来合并成一个字符串
   myWidget->setStyleSheet("QWidget { background-color: #3a3a3a }""QPushButton { background-color: yellow }");// 也可以直接对控件设置样式
   auto myButton = new QPushButton();
   myButton->setStyleSheet("background-color: yellow");

---

2. QSS选择器

2.1 选择器类型

QSS支持多种选择器，常用的包括：

1. 类型选择器：根据控件类型应用样式。具体支持的控件类型见2.2。

   QPushButton {color: red;
   }
   

2. 类选择器：根据控件的objectName或class属性应用样式，使用**#**来指定控件名称。

   可以先使用控件的getObjectName()方法获取控件名称，或者使用setObjectName(QString name)方法来指定控件名称

   QPushButton#myButton { /* 允许省略QPushButton */background-color: green;
   }
   

   // 设置、查看控件名称
   auto myButton = new QPushButton();
   myWidget->setObjectName("myButton");
   myWidget->getObjectName(); // 返回"myButton"
   

3. 子控件选择器：针对复合控件的子部件应用样式，使用**::**来指定子控件。

   QComboBox::drop-down { /* 下拉按钮 */image: url(dropdown.png); /* 自定义箭头图标 */
   }
   

4. 状态选择器：根据控件的状态（如hover、pressed）应用样式，使用**:**来指定控件状态。

   QPushButton:hover {background-color: yellow;
   }
   

2.2 选择器控件列表

控件类型	说明	子部件	伪状态
QWidget	所有控件的基类，支持通用样式属性（如背景颜色、边框等）。	无	无
QAbstractScrollArea	滚动区域的抽象基类，支持滚动条样式。	::corner（滚动条交汇处的角落区域），::viewport（滚动区域的内容视图）	无
QDialog	对话框的基类，支持对话框窗口和子控件的样式。	无	无
QAbstractButton	抽象按钮基类，支持按钮样式（如文本、图标、背景等）。	无	:hover（鼠标悬停时），:pressed（鼠标按下时），:checked（按钮被选中时），:unchecked（按钮未被选中时），:disabled（按钮被禁用时）
QPushButton	标准按钮控件，支持按钮样式。	无	:hover（鼠标悬停时），:pressed（鼠标按下时），:checked（按钮被选中时），:unchecked（按钮未被选中时），:disabled（按钮被禁用时），:default（默认按钮），:flat（扁平化按钮）
QRadioButton	单选按钮控件，支持单选按钮样式。	无	:hover（鼠标悬停时），:pressed（鼠标按下时），:checked（按钮被选中时），:unchecked（按钮未被选中时），:disabled（按钮被禁用时）
QCheckBox	复选框控件，支持复选框样式。	无	:hover（鼠标悬停时），:pressed（鼠标按下时），:checked（按钮被选中时），:unchecked（按钮未被选中时），:indeterminate（不确定状态），:disabled（按钮被禁用时）
QComboBox	下拉框控件，支持下拉按钮、箭头、列表项等子控件样式。	::drop-down（下拉按钮），::down-arrow（下拉箭头），::item（下拉列表中的项），::indicator（选中指示器）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（控件被禁用时），:on（下拉框打开时），:off（下拉框关闭时）
QScrollBar	滚动条控件，支持滑块、增加/减少按钮等子控件样式。	::handle（滑块），::add-line（增加按钮），::sub-line（减少按钮），::add-page（滑块上方的背景区域），::sub-page（滑块下方的背景区域）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（滚动条被禁用时）
QSlider	滑块控件，支持滑块手柄样式。	::groove（滑槽），::handle（滑块手柄），::add-page（滑块上方的背景区域），::sub-page（滑块下方的背景区域）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（滑块被禁用时）
QProgressBar	进度条控件，支持进度块样式。	::chunk（进度块）	:hover（鼠标悬停时），:disabled（进度条被禁用时）
QTabWidget	标签页控件，支持标签栏、标签页等子控件样式。	::pane（标签页的内容区域），::tab-bar（标签栏）	:hover（鼠标悬停时），:disabled（控件被禁用时）
QTabBar	标签栏控件，支持标签页样式。	::tab（标签页），::close-button（关闭按钮），::tear（拖拽分离的标签），::scroller（滚动按钮）	:hover（鼠标悬停时），:selected（标签页被选中时），:disabled（标签页被禁用时）
QHeaderView	表头控件，支持表格或树形视图的表头样式。	::section（表头单元格）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（表头被禁用时）
QMenu	菜单控件，支持菜单项、分隔符等样式。	::item（菜单项），::separator（分隔符），::indicator（选中指示器），::right-arrow（右箭头），::left-arrow（左箭头）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（菜单项被禁用时），:checked（菜单项被选中时），:unchecked（菜单项未被选中时）
QMenuBar	菜单栏控件，支持菜单栏项样式。	::item（菜单栏项）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（菜单栏项被禁用时）
QToolBar	工具栏控件，支持工具栏按钮、分隔符等样式。	::separator（分隔符），::handle（拖动手柄）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（工具栏被禁用时）
QDockWidget	停靠窗口控件，支持标题栏、关闭按钮等样式。	::title（标题栏），::close-button（关闭按钮），::float-button（浮动按钮）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（停靠窗口被禁用时）
QStatusBar	状态栏控件，支持状态栏消息样式。	无	无
QMainWindow	主窗口控件，支持中央部件、工具栏、状态栏等样式。	无	无
QLineEdit	单行文本输入框控件，支持文本、占位符、边框等样式。	::clear-button（清除按钮），::up-button（向上按钮），::down-button（向下按钮）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（输入框被禁用时），:read-only（只读模式）
QTextEdit	多行文本编辑框控件，支持文本、滚动条等样式。	::corner（滚动条交汇处的角落区域），::viewport（滚动区域的内容视图）	:hover（鼠标悬停时），:disabled（文本编辑框被禁用时）
QPlainTextEdit	纯文本编辑框控件，支持文本、滚动条等样式。	::corner（滚动条交汇处的角落区域），::viewport（滚动区域的内容视图）	:hover（鼠标悬停时），:disabled（纯文本编辑框被禁用时）
QSpinBox	数值输入框控件，支持上下箭头按钮、文本等样式。	::up-button（向上按钮），::down-button（向下按钮），::up-arrow（向上箭头），::down-arrow（向下箭头）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（数值输入框被禁用时）
QDoubleSpinBox	双精度数值输入框控件，支持上下箭头按钮、文本等样式。	::up-button（向上按钮），::down-button（向下按钮），::up-arrow（向上箭头），::down-arrow（向下箭头）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（双精度数值输入框被禁用时）
QDateTimeEdit	日期时间输入框控件，支持上下箭头按钮、文本等样式。	::up-button（向上按钮），::down-button（向下按钮），::up-arrow（向上箭头），::down-arrow（向下箭头）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（日期时间输入框被禁用时）
QAbstractItemView	抽象项视图基类，支持表格、列表、树形视图的样式。	::item（项），::branch（分支节点），::indicator（选中指示器）	:hover（鼠标悬停时），:selected（项被选中时），:disabled（项被禁用时），:checked（项被选中时），:unchecked（项未被选中时）
QSplitter	分割器控件，支持分割线样式。	::handle（拖动手柄）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（分割器被禁用时）
QCalendarWidget	日历控件，支持日历网格、选中日期等样式。	::navigation-bar（导航栏），::month-button（月份按钮），::year-button（年份按钮），::prev-month-button（上一月按钮），::next-month-button（下一月按钮）	:hover（鼠标悬停时），:pressed（鼠标按下时），:disabled（日历控件被禁用时）

---

3. QSS属性列表

以下是QSS支持的常用属性及其详细说明：

3.1 颜色与背景

属性	描述	示例
color	设置文本颜色	color: red;
background-color	设置背景颜色	background-color: blue;
background-image	设置背景图片	background-image: url(bg.png);
background	设置背景颜色和图片	background: red url(bg.png);
background-repeat	设置背景图片重复方式	background-repeat: no-repeat;
background-position	设置背景图片位置	background-position: center;

3.2 字体

属性	描述	示例
font-family	设置字体名称	font-family: Arial;
font-size	设置字体大小	font-size: 14px;
font-weight	设置字体粗细	font-weight: bold;
font-style	设置字体样式（如斜体）	font-style: italic;
font	综合设置字体属性	font: bold 14px Arial;

3.3 边框

属性	描述	示例
border	设置边框样式	border: 1px solid black;
border-radius	设置圆角半径	border-radius: 5px;
border-color	设置边框颜色	border-color: red;
border-width	设置边框宽度	border-width: 2px;
border-style	设置边框样式（如实线、虚线）	border-style: dashed;

3.4 间距与对齐

属性	描述	示例
padding	设置内边距	padding: 10px;
margin	设置外边距	margin: 5px;
text-align	设置文本对齐方式	text-align: center;
spacing	设置控件内部间距	spacing: 5px;
alignment	设置内容对齐方式	alignment: Qt::AlignCenter;

3.5 其他属性

属性	描述	示例
min-width	设置最小宽度	min-width: 100px;
max-width	设置最大宽度	max-width: 200px;
min-height	设置最小高度	min-height: 50px;
max-height	设置最大高度	max-height: 100px;
opacity	设置透明度	opacity: 0.5;
icon	设置图标	icon: url(icon.png);
image	设置图片	image: url(image.png);

---

4. QSS的高级用法

以下是Qt样式表（QSS）的高级用法详解。

4.1 伪状态组合（多状态叠加控制）

QSS允许通过组合多个伪状态实现精确的交互反馈。

QPushButton:hover:checked { /* 按钮同时悬停且被选中 */background-color: #FFA500;  /* 橙色 */border: 2px solid darkorange;
}

4.2 继承与层叠机制

QSS遵循CSS的层叠规则，但需注意Qt控件的样式继承特性。即前面提到的子控件可以在父控件之上设置样式。

QWidget {font-family: "Arial";font-size: 12pt;
}QPushButton { /* 是QWidget的子控件 *//* 继承自QWidget的字体设置 */color: white;
}

4.3 动态属性与条件样式

通过QObject::setProperty()动态改变控件样式。

先在代码中设置属性：

button->setProperty("priority", "high");

然后可以在QSS中匹配属性，以指定设置样式表：

QPushButton[priority="high"] {background-color: #FF4444;font-weight: bold;
}

附高级用法：状态切换动画

// 通过属性切换实现动画效果
button->setProperty("state", "active");
qApp->style()->unpolish(button);
qApp->style()->polish(button);

4.4 复杂选择器组合

通过组合选择器实现精准样式定位。

1. 相邻兄弟选择器

   QLineEdit + QPushButton {margin-left: 10px;  /* 紧接在输入框后的按钮 */
   }
   

2. 层级嵌套选择

   QTabWidget > QTabBar::tab:first-child {border-radius: 5px 0 0 0;  /* 第一个标签页特殊样式 */
   }
   

4.5 自定义控件样式

为自定义Widget实现完整QSS支持，可以自定义可样式化的子部件，如下：

class CustomWidget : public QWidget {Q_OBJECTQ_PROPERTY(QString mode READ mode WRITE setMode)
public:// 注册子部件类型Q_ENUMS(SubControls)enum SubControls { SC_Indicator = 0x1 };
};

然后在QSS中可以设置样式表：

CustomWidget::indicator {width: 20px;height: 20px;
}

4.6 高效调试技巧

在实际编码过程中，常用如下几种快速定位样式问题的方法。

1. 样式探测器

   qDebug() << widget->styleSheet();  // 输出当前样式
   

2. 边界高亮法

   * {border: 1px solid red !important;  /* 显示所有控件边界 */
   }
   

3. 状态监测法

   // 打印控件状态
   qDebug() << "Hover:" << button->underMouse()<< "Pressed:" << button->isDown();
   

4.7 性能优化策略

• 避免全局选择器：尽量使用ID或类选择器
• 合并重复样式：减少重复属性定义
• 预编译QSS：将样式表编译为二进制资源
• 分层加载：按模块动态加载样式表

/* 优化前 */
QPushButton#okBtn { color: white; }
QPushButton#cancelBtn { color: white; }/* 优化后 */
#okBtn, #cancelBtn {color: white;
}