QDarkStyleSheet: 一个Qt应用的暗色主题解决方案

[2.1.Python Qt（PyQt/PySide）集成](#2.1.Python Qt（PyQt/PySide）集成)

[2.2.C++ Qt 集成](#2.2.C++ Qt 集成)

1.简介

QDarkStyleSheet 是一套专为 Qt 框架 （包括 C++ Qt 和 Python Qt 绑定如 PyQt、PySide）设计的 暗色风格样式表（Qt Style Sheet, QSS）集合，旨在为 Qt 应用快速提供美观、统一的暗色主题，解决 Qt 默认样式单一、视觉体验不足的问题，尤其适合需要长时间使用的应用（如 IDE、数据可视化工具、桌面客户端）。

Qt Style Sheet（QSS）是 Qt 模仿 CSS 语法的界面样式定义语言，可自定义控件（如按钮、菜单、表格、对话框）的颜色、字体、布局、状态（ hover / 点击）等视觉属性。

QDarkStyleSheet 并非独立库，而是预编写好的 QSS 规则集合，封装了对 Qt 原生控件的暗色样式适配，开发者无需手动编写复杂的 QSS，只需简单集成即可让整个应用切换为暗色主题。

它的特点有：

1.跨平台兼容性

完全继承 Qt 的跨平台特性，支持 Windows（32/64 位）、macOS、Linux 等主流桌面系统，且在不同系统下保持视觉一致性。

2.广泛的 Qt 版本支持

兼容 Qt 5.x、Qt 6.x 系列，同时适配 Python Qt 绑定：

PyQt5 / PyQt6
PySide2 / PySide6
C++ Qt 5 / Qt 6

3.美观且统一的设计

采用现代暗色设计，主色调以深灰 / 黑色为底，搭配高对比度的文字和控件（如蓝色按钮、浅灰文本），降低视觉疲劳。
覆盖 Qt 几乎所有原生控件：窗口、按钮、输入框、下拉菜单、表格、树控件、进度条、滑块等，避免 "局部亮色、局部暗色" 的割裂感。
支持 高 DPI 显示，自动适配高分屏，避免样式模糊。

4.极低的集成成本

无需修改应用核心逻辑，仅需 2-3 行代码即可加载样式表，新手也能快速上手。

5.开源免费

基于 MIT 许可证开源，源码托管于 GitHub，可自由使用、修改和二次分发。

2.安装与使用

QDarkStyleSheet 的使用流程简单，核心是 "加载预定义的 QSS 文件 / 字符串"，不同开发语言（Python/C++）的集成方式略有差异。

2.1.Python Qt（PyQt/PySide）集成

步骤 1：安装 QDarkStyleSheet

通过 pip 直接安装（Python 3.6+ 支持）：

cpp 复制代码

pip install qdarkstyle

步骤 2：在代码中加载样式表

根据使用的 Qt 绑定（PyQt5/PyQt6/PySide2/PySide6），调用对应的加载函数即可。

示例 1：PyQt5

cpp 复制代码

import sys
from PyQt5.QtWidgets import QApplication, QMainWindow, QPushButton

# 导入 QDarkStyleSheet
import qdarkstyle

class MyWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.initUI()

    def initUI(self):
        self.setWindowTitle("QDarkStyleSheet 示例（PyQt5）")
        self.resize(400, 300)
        # 添加一个测试按钮
        btn = QPushButton("测试按钮", self)
        btn.move(150, 150)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    
    # 加载 PyQt5 对应的暗色样式表
    app.setStyleSheet(qdarkstyle.load_stylesheet_pyqt5())
    
    window = MyWindow()
    window.show()
    sys.exit(app.exec_())

示例 2：PyQt6

PyQt6 需使用 load_stylesheet_pyqt6() 函数：

cpp 复制代码

# 替换加载样式表的代码
app.setStyleSheet(qdarkstyle.load_stylesheet_pyqt6())

示例 3：PySide2/PySide6

对应函数为 load_stylesheet_pyside2() / load_stylesheet_pyside6()：

cpp 复制代码

# PySide6 示例
app.setStyleSheet(qdarkstyle.load_stylesheet_pyside6())

2.2.C++ Qt 集成

C++ 环境需手动获取 QSS 文件，再通过代码读取并应用。

步骤 1：获取 QSS 文件

1.从 GitHub 下载源码：

https://github.com/ColinDuquesnoy/QDarkStyleSheet

2.在源码的 qdarkstyle 目录中找到 qdarkstyle.qss（核心样式文件）。

步骤 2：将 QSS 文件加入项目资源

如果是QtCreator中，则是将 darkstyle.qrc 添加到项目的 .pro 文件中：

cpp 复制代码

RESOURCES += darkstyle.qrc

如果是vs中，则是直接将 darkstyle.qrc导入到工程中

步骤 3：在代码中加载样式表

cpp 复制代码

#include <QApplication>
#include <QFile>
#include <QLatin1String>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);

    // 读取 QSS 文件
    QFile qssFile(":/qdarkstyle.qss");  // 路径对应资源文件中的前缀+文件名
    if (qssFile.open(QFile::ReadOnly)) {
        // 将 QSS 内容设置为应用全局样式
        QString styleSheet = QLatin1String(qssFile.readAll());
        a.setStyleSheet(styleSheet);
        qssFile.close();
    }

    // 后续创建窗口并显示
    MainWindow w;
    w.show();

    return a.exec();
}

3.配置与自定义

QDarkStyleSheet 支持灵活的样式调整，满足个性化需求，主要有两种方式：

1.直接修改 QSS 文件

打开 qdarkstyle.qss，找到对应控件的样式规则，修改颜色、字体等属性：

例如，修改按钮的默认背景色：

cpp 复制代码

/* 原规则 */
QPushButton {
    background-color: #2a2a2a;
    color: #ffffff;
    border: 1px solid #444444;
    padding: 5px 10px;
}

/* 修改后（将背景色改为深蓝色） */
QPushButton {
    background-color: #1a365d;
    color: #ffffff;
    border: 1px solid #2a5082;
    padding: 5px 10px;
}

2.代码中动态覆盖样式

加载 QDarkStyleSheet 后，通过额外的 QSS 字符串覆盖原有规则，无需修改原文件：

cpp 复制代码

# 先加载默认暗色样式
app.setStyleSheet(qdarkstyle.load_stylesheet_pyqt5())

# 再添加自定义样式（覆盖按钮背景色和窗口标题栏颜色）
custom_style = """
QPushButton {
    background-color: #ff4444;  /* 红色按钮 */
    border-radius: 4px;         /* 圆角 */
}
QMainWindow::titleBar {
    background-color: #333333;  /* 标题栏深灰 */
}
"""
# 合并样式（后加载的规则优先级更高）
app.setStyleSheet(app.styleSheet() + custom_style)