使用指南

StyleKit 使用指南

本章参考 UIGearsStyleKitPreview 示例程序，说明如何在 Qt Widgets 项目中加载 StyleKit、切换主题并组织样式文件。

运行示例程序

StyleKit 示例工程位于 UIGearsStyleKit/UIGearsStyleKit，用于预览 QSS 主题、控件状态和图标资源。

cmake --build UIGearsStyleKit/UIGearsStyleKit/build-debug --config Debug --target UIGearsStyleKitPreview --parallel
UIGearsStyleKit/UIGearsStyleKit/build-debug/Debug/UIGearsStyleKitPreview.exe

构建后，CMake 会把 styles 目录复制到可执行文件同级目录，示例程序优先从运行目录读取 QSS。这样发布预览包时，只需要保留 exe 与 styles 目录即可。

样式目录

推荐保持如下目录结构：

styles/
  light.qss
  blueLight.qss
  dark.qss
  vs17Light.qss
  ...

每个 qss 文件顶部包含 @palette 元数据，用于说明主题色、文本色、背景色和高亮色。应用运行时不依赖这些注释，但它们可以作为设计、文档和后续生成工具的统一来源。

加载 QSS

示例程序中的加载顺序为：

<applicationDir>/styles
<currentWorkingDirectory>/styles
编译时传入的源码目录 UIGEAR_STYLE_DIR

项目中可以采用同样策略，先查找运行目录，再回退到开发目录。

static QString readStyleSheet(const QString& path)
{
    QFile file(path);
    if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) {
        return {};
    }
    return QString::fromUtf8(file.readAll());
}

QString qss = readStyleSheet(QCoreApplication::applicationDirPath() + "/styles/blueLight.qss");
qApp->setStyleSheet(qss);

常用调用方法：

方法	说明	参数	返回值
`readStyleSheet(const QString& path)`	读取指定路径的 QSS 文件内容。	`path`：QSS 文件路径。	`QString`，读取失败时为空字符串
`QCoreApplication::applicationDirPath()`	获取应用程序所在目录，用于定位发布目录下的 `styles`。	无	`QString`
`qApp->setStyleSheet(qss)`	将 QSS 应用到整个 Qt 应用。	`qss`：样式表字符串。	`void`

切换主题

切换主题时只需要重新读取目标 qss，并调用 qApp->setStyleSheet(...)。示例中的主题切换窗口会根据按钮选择加载不同文件，例如 light.qss、blueLight.qss、dark.qss。

void applyTheme(const QString& themeFile)
{
    const QString path = QCoreApplication::applicationDirPath() + "/styles/" + themeFile;
    const QString qss = readStyleSheet(path);
    if (!qss.isEmpty()) {
        qApp->setStyleSheet(qss);
    }
}

主题切换相关方法：

方法	说明	参数	返回值
`applyTheme(const QString& themeFile)`	根据主题文件名加载并应用 QSS。	`themeFile`：主题文件名，例如 `blueLight.qss`。	`void`
`qss.isEmpty()`	判断读取到的 QSS 是否为空。	无	`bool`
`qApp->setStyleSheet(qss)`	重新应用当前主题样式。	`qss`：样式表字符串。	`void`

控件属性

StyleKit 通过 Qt 标准选择器、对象名和动态属性组织状态。业务代码可以通过属性选择不同变体：

QPushButton* saveButton = new QPushButton(tr("Save"), this);
saveButton->setProperty("variant", "primary");

QProgressBar* progress = new QProgressBar(this);
progress->setProperty("variant", "success");

设置动态属性后，如果控件已经显示，建议刷新一次样式：

saveButton->style()->unpolish(saveButton);
saveButton->style()->polish(saveButton);
saveButton->update();

动态属性刷新方法：

方法	说明	参数	返回值
`setProperty(const char* name, const QVariant& value)`	设置 Qt 动态属性，用于匹配 QSS 属性选择器。	`name`：属性名；`value`：属性值。	`bool`，属性是否设置成功
`style()->unpolish(widget)`	移除控件当前样式缓存。	`widget`：需要刷新的控件。	`void`
`style()->polish(widget)`	重新计算控件样式。	`widget`：需要刷新的控件。	`void`
`update()`	触发控件重绘。	无	`void`

滚动区域

StyleKit 已覆盖 QScrollBar 与 QAbstractScrollArea::corner。如果页面包含 QTableWidget、QTreeWidget、QListWidget、QTextEdit 等滚动控件，不需要单独写滚动条样式；滚动条会自动跟随当前主题的背景色、高亮色和禁用文本色。

发布建议

将 styles 目录随应用一起发布。
不建议在多个页面分别设置全局 QSS，统一在应用启动或主题切换处加载。
业务页面只设置对象名、动态属性和必要的布局参数，避免把颜色硬编码在页面代码里。
自定义控件如果继承 Qt 标准控件，优先复用现有选择器；只有新的视觉结构才增加专用对象名。

Qt-UI StyleKit 使用指南