{
  "schemaVersion": "0.11.0",
  "canonical": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/",
  "atlas": "https://www.pystone.net/?node=pyqt-qss-selector-syntax#knowledge-atlas",
  "markdown": "https://www.pystone.net/notes/pyqt-qss-selector-syntax.md",
  "context": "https://www.pystone.net/notes/pyqt-qss-selector-syntax.context.json",
  "knowledgeVersion": "224c990773de.5fa8af6e39fa",
  "build": {
    "siteCommit": "224c990773de166d23a886306577dd90379529ce",
    "notesCommit": "5fa8af6e39fa3891d1b9b4832bfa6c4e0ecaaf0a",
    "builtAt": "1970-01-01T00:00:00.000Z",
    "version": "224c990773de.5fa8af6e39fa"
  },
  "id": "note:pyqt-qss-selector-syntax",
  "slug": "pyqt-qss-selector-syntax",
  "title": "PyQt开发-QSS 选择器语法指南",
  "type": "note",
  "visibility": "public",
  "idStability": "rename-stable",
  "author": {
    "name": "Perrin Yong",
    "profile": "https://www.pystone.net/profile/"
  },
  "publisher": {
    "name": "Perrin Yong",
    "profile": "https://www.pystone.net/profile/"
  },
  "aliases": [],
  "summary": "![](assets/image 20250212222619282.png)",
  "contentRole": "unspecified",
  "isMoc": false,
  "mocRecognition": "none",
  "generated": false,
  "attribution": "unspecified",
  "domain": "10-计算机、信息技术与工程",
  "tags": [],
  "mocs": [],
  "contentHash": "45b8c69ae21962a7d675c3a378e5f0649ad3ed467109bf2ff7cb1d488416895b",
  "assets": [
    {
      "reference": "assets/image-20250212222619282.png",
      "url": "/media/b36d600fc746b2706835.png",
      "mediaType": "image/png",
      "contentHash": "b36d600fc746b27068350945145a7617ca657359b7076879a4d0cb511bc387eb",
      "byteLength": 1061085,
      "width": 1600,
      "height": 840
    },
    {
      "reference": "assets/image-20240202125015625.png",
      "url": "/media/26ad8ecf72e4d7fb089b.png",
      "mediaType": "image/png",
      "contentHash": "26ad8ecf72e4d7fb089bf846d4b4ff913343b5e527937db7337f21e771f9de72",
      "byteLength": 25427,
      "width": 527,
      "height": 454
    }
  ],
  "headings": [
    {
      "depth": 1,
      "text": "PyQt开发-QSS 选择器语法指南",
      "anchor": "pyqt开发-qss-选择器语法指南",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#pyqt%E5%BC%80%E5%8F%91-qss-%E9%80%89%E6%8B%A9%E5%99%A8%E8%AF%AD%E6%B3%95%E6%8C%87%E5%8D%97"
    },
    {
      "depth": 2,
      "text": "1. 选择器概述",
      "anchor": "1-选择器概述",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#1-%E9%80%89%E6%8B%A9%E5%99%A8%E6%A6%82%E8%BF%B0"
    },
    {
      "depth": 2,
      "text": "2. 选择器类型",
      "anchor": "2-选择器类型",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#2-%E9%80%89%E6%8B%A9%E5%99%A8%E7%B1%BB%E5%9E%8B"
    },
    {
      "depth": 3,
      "text": "2.1 类型（Type）选择器",
      "anchor": "21-类型type选择器",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#21-%E7%B1%BB%E5%9E%8Btype%E9%80%89%E6%8B%A9%E5%99%A8"
    },
    {
      "depth": 3,
      "text": "2.2 类（Class）选择器",
      "anchor": "22-类class选择器",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#22-%E7%B1%BBclass%E9%80%89%E6%8B%A9%E5%99%A8"
    },
    {
      "depth": 3,
      "text": "2.3 ID（ObjectName）选择器",
      "anchor": "23-idobjectname选择器",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#23-idobjectname%E9%80%89%E6%8B%A9%E5%99%A8"
    },
    {
      "depth": 3,
      "text": "2.4 属性（Property）选择器",
      "anchor": "24-属性property选择器",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#24-%E5%B1%9E%E6%80%A7property%E9%80%89%E6%8B%A9%E5%99%A8"
    },
    {
      "depth": 3,
      "text": "2.5 包含（Descendant）选择器",
      "anchor": "25-包含descendant选择器",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#25-%E5%8C%85%E5%90%ABdescendant%E9%80%89%E6%8B%A9%E5%99%A8"
    },
    {
      "depth": 3,
      "text": "2.6 子元素（Child）选择器",
      "anchor": "26-子元素child选择器",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#26-%E5%AD%90%E5%85%83%E7%B4%A0child%E9%80%89%E6%8B%A9%E5%99%A8"
    },
    {
      "depth": 3,
      "text": "2.7 伪类选择器",
      "anchor": "27-伪类选择器",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#27-%E4%BC%AA%E7%B1%BB%E9%80%89%E6%8B%A9%E5%99%A8"
    },
    {
      "depth": 3,
      "text": "2.8 Subcontrol 选择器",
      "anchor": "28-subcontrol-选择器",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#28-subcontrol-%E9%80%89%E6%8B%A9%E5%99%A8"
    },
    {
      "depth": 2,
      "text": "3. QSS 在工程中的用法",
      "anchor": "3-qss-在工程中的用法",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#3-qss-%E5%9C%A8%E5%B7%A5%E7%A8%8B%E4%B8%AD%E7%9A%84%E7%94%A8%E6%B3%95"
    },
    {
      "depth": 3,
      "text": "3.1 代码动态设置 QSS",
      "anchor": "31-代码动态设置-qss",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#31-%E4%BB%A3%E7%A0%81%E5%8A%A8%E6%80%81%E8%AE%BE%E7%BD%AE-qss"
    },
    {
      "depth": 4,
      "text": "全局 QSS 设置",
      "anchor": "全局-qss-设置",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#%E5%85%A8%E5%B1%80-qss-%E8%AE%BE%E7%BD%AE"
    },
    {
      "depth": 4,
      "text": "局部 QSS 设置",
      "anchor": "局部-qss-设置",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#%E5%B1%80%E9%83%A8-qss-%E8%AE%BE%E7%BD%AE"
    },
    {
      "depth": 3,
      "text": "3.2 使用 Qt Designer 编写 QSS",
      "anchor": "32-使用-qt-designer-编写-qss",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#32-%E4%BD%BF%E7%94%A8-qt-designer-%E7%BC%96%E5%86%99-qss"
    },
    {
      "depth": 2,
      "text": "4. QSS 美化素材与工具",
      "anchor": "4-qss-美化素材与工具",
      "citation": "https://www.pystone.net/notes/pyqt-qss-selector-syntax/#4-qss-%E7%BE%8E%E5%8C%96%E7%B4%A0%E6%9D%90%E4%B8%8E%E5%B7%A5%E5%85%B7"
    }
  ],
  "claims": [],
  "outgoing": [],
  "incoming": [
    {
      "id": "note:application-and-cloud-engineering",
      "title": "应用开发与云端工程",
      "url": "https://www.pystone.net/notes/application-and-cloud-engineering/",
      "atlas": "https://www.pystone.net/?node=application-and-cloud-engineering#knowledge-atlas",
      "label": "应用开发与云端工程",
      "origin": "explicit",
      "humanReviewed": true,
      "context": "桌面应用开发中的“PyQt开发-QSS 选择器语法指南”导航项",
      "citation": "https://www.pystone.net/notes/application-and-cloud-engineering/#%E6%A1%8C%E9%9D%A2%E5%BA%94%E7%94%A8%E5%BC%80%E5%8F%91"
    }
  ],
  "contentMarkdown": "![](assets/image-20250212222619282.png)\n\n\n# PyQt开发-QSS 选择器语法指南\n## 1. 选择器概述\n\nQSS 选择器用于选择一个或多个需要应用样式的 Qt 部件。详细文档可参考：[Qt 官方 QSS 语法文档](https://doc.qt.io/qt-5/stylesheet-syntax.html)\n\n## 2. 选择器类型\n\n### 2.1 类型（Type）选择器\n\n```css\nQFrame {\n   background: gray;\n}\n```\n\n作用于所有 `QFrame` 控件。\n\n### 2.2 类（Class）选择器\n\n`. + 类名` 或者 `. + class 的属性值` 作为选择器（使用 setProperty(“class”, “QSSClassName”) 设置），只会作用于它自己，它的子类不受影响，注意和类型选择器的区别。\n\n```python\n\n#include <QApplication>\n#include <QPushButton>\n#include <QHBoxLayout>\nint main(int argc, char *argv[]) {\n\tQApplication app(argc, argv);\n\tapp.setStyleSheet(\"QWidget { background: gray; }\");\n\tQWidget *window = new QWidget();\n\tQPushButton *openButton = new QPushButton(\"打开\", window);\n\tQPushButton *closeButton = new QPushButton(\"关闭\", window);\n\tQPushButton *saveButton = new QPushButton(\"保存\", window);\n\tQHBoxLayout *layout = new QHBoxLayout(window);\n\tlayout->addWidget(openButton);\n\tlayout->addWidget(closeButton);\n\tlayout->addWidget(saveButton);\n\twindow->setLayout(layout);\n\twindow->show();\n\treturn app.exec();\n\n}\n\n```\n\n如果只想要 window 的背景是灰色的，按钮的背景不变，可以使用类选择器 `.QWidget`\n\n```python\n## 把 QWidget 改成 .QWidget\napp.setStyleSheet(\".QWidget {background: gray;}\")\n```\n\n设置某个组件的类名\n\n```python\napp.setStyleSheet(\".QWidget { background: gray; }\"\n\".RedButton { background: magenta; }\");\n## .RedButton 将作为类选择器\nopenButton->setProperty(\"class\", \"RedButton\");\ncloseButton->setProperty(\"class\", \"RedButton\");\n```\n\n### 2.3 ID（ObjectName）选择器\n\n`# + objectName` 作为选择器，仅作用于指定 objectName 的对象。\n\n```python\napp.setStyleSheet(\".QWidget { background: gray; }\"\n                  \"#openButton, #closeButton { background: magenta; }\");\n\nopenButton->setObjectName(\"openButton\");\ncloseButton->setObjectName(\"closeButton\");\n```\n\n### 2.4 属性（Property）选择器\n\n基于动态属性匹配元素：\n\n```python\napp.setStyleSheet(\".QWidget { background: gray; }\"\n                  \"QPushButton[level='dangerous'] { background: magenta; }\");\n\nopenButton->setProperty(\"level\",  \"dangerous\");\ncloseButton->setProperty(\"level\", \"dangerous\");\n```\n\n### 2.5 包含（Descendant）选择器\n\n用于选择某个 Widget 的所有子 Widget：\n\n```css\nQFrame {\n    background: gray;\n}\nQFrame QPushButton {\n    border: 2px solid magenta;\n    border-radius: 10px;\n    background: white;\n    padding: 2px 15px;\n}\n```\n\n### 2.6 子元素（Child）选择器\n\n仅作用于 Widget 的直接子 Widget：\n\n```css\nQFrame {\n    background: gray;\n}\nQFrame > QPushButton {\n    border: 2px solid magenta;\n    border-radius: 10px;\n    background: white;\n    padding: 2px 15px;\n}\n```\n\n### 2.7 伪类选择器\n\n基于组件状态匹配：\n\n```css\nQPushButton:hover { color: white }\nQCheckBox:checked { color: white }\nQCheckBox:!checked { color: red }\nQCheckBox:hover:checked { color: white }\n```\n\n### 2.8 Subcontrol 选择器\n\n某些 Widget 由多个部分组成，例如 `QCheckBox` 包含 `indicator` 和 `text`，可使用 `选择器::subcontrol` 设置样式。\n\n|Subcontrol|说明|\n|---|---|\n|`::indicator`|适用于 `QCheckBox`、`QRadioButton`、`QMenuItem` 等的指示器|\n|`::menu-indicator`|`QPushButton` 的菜单指示器|\n|`::up-button`|`QSpinBox` 或 `QScrollBar` 的上按钮|\n|`::down-button`|`QSpinBox` 或 `QScrollBar` 的下按钮|\n|`::drop-down`|`QComboBox` 的下拉箭头|\n|`::title`|`QGroupBox` 或 `QDockWidget` 的标题|\n|`::chunk`|`QProgressBar` 进度条的块|\n\n## 3. QSS 在工程中的用法\n\n### 3.1 代码动态设置 QSS\n\n#### **全局 QSS 设置**\n\n```python\nif __name__ == '__main__':\n    app = QApplication(sys.argv)\n    mainWindow = MainWindow()\n    styleFile = './qss/style.qss'\n\n    with open(styleFile, 'r') as f:\n        style = f.read()\n        mainWindow.setStyleSheet(style)\n    mainWindow.show()\n    sys.exit(app.exec_())\n```\n\n#### **局部 QSS 设置**\n\n```python\nbtn1.setStyleSheet('''\n    QPushButton{\n        color:red;\n    }\n    QPushButton:hover{\n        background-color: green;\n    }\n''')\n\nlabel3.setStyleSheet('background-color:yellow;font-size:30px;')\n```\n\n### 3.2 使用 Qt Designer 编写 QSS\n\n可在 Qt Designer 的 **属性编辑器** 中直接编辑 QSS 文件，使界面风格可视化调整。\n![](assets/image-20240202125015625.png)\n\n\n## 4. QSS 美化素材与工具\n\n- **[Qt-Material](https://qt-material.readthedocs.io/en/latest/index.html#qt-material)**：适用于 PySide6、PySide2 和 PyQt5 的 Material Design 主题样式表。\n- **[QDarkStyleSheet](https://github.com/ColinDuquesnoy/QDarkStyleSheet)**：提供现代化的黑暗风格 QSS。\n- **[PyQt5 Stylesheets](https://github.com/RedFalsh/PyQt5_stylesheets)**：多个 PyQt5 风格样式表集合。\n\n\n以上是 QSS 选择器的语法和工程实践，希望能帮助你更好地进行 Qt 界面美化和开发！```\n"
}