SARibbon主题切换

• ✅ 6种内置主题：Office2013/2016/2021、Windows7、Dark/Dark2，一键切换
• ✅ 运行时动态切换：通过 setRibbonTheme() 即时更换主题，无需重启
• ✅ QSS合并机制：内置主题QSS可与自定义样式合并，不会互相覆盖
• ✅ 完全自定义主题：基于QSS编写任意风格，参见 自定义Ribbon主题

主题切换流程

flowchart TD
    A[调用 setRibbonTheme] --> B{是否有自定义 QSS?}
    B -->|否| C[直接应用内置主题 QSS]
    B -->|是| D[先调用 setRibbonTheme 设置内置主题]
    D --> E[再调用 setStyleSheet 合并自定义QSS]
    C --> G[界面更新完成]
    E --> G

SARibbon 提供了多种内置主题，如 Windows 7、Office 2013、Office 2016、暗色主题等，主题定义在SARibbonTheme枚举类中：

enum class SARibbonTheme
{
    RibbonThemeOffice2013,      ///< office2013主题
    RibbonThemeOffice2016Blue,  ///< office2016-蓝色主题
    RibbonThemeOffice2021Blue,  ///< office2021-蓝色主题
    RibbonThemeWindows7,        ///< win7主题
    RibbonThemeDark,            ///< 暗色主题
    RibbonThemeDark2            ///< 暗色主题2
};

通过SARibbonMainWindow::setRibbonTheme/SARibbonWidget::setRibbonTheme函数，可以设置Ribbon的主题，此函数的参数为SARibbonTheme对象

注意

某些Qt版本，在构造函数设置主题会不完全生效，可以使用QTimer投放到队列最后执行：

MainWindow::MainWindow(QWidget* par) : SARibbonMainWindow(par)
{
    ...
    QTimer::singleShot(0, this, [ this ]() {
        this->setRibbonTheme(SARibbonTheme::RibbonThemeDark);
    });
}

各个主题效果如下图所示：

win7主题：

office2013主题：

office2016主题：

office2021主题：

dark主题：

dark2主题：

主题对照表

枚举值	风格说明	适用场景
RibbonThemeOffice2013	Office 2013 经典白色	追求简洁明亮风格
RibbonThemeOffice2016Blue	Office 2016 蓝色调	商务/企业应用
RibbonThemeOffice2021Blue	Office 2021 蓝色调	现代化界面设计
RibbonThemeWindows7	Windows 7 经典	兼容传统风格
RibbonThemeDark	暗色主题	长时间使用/夜间模式
RibbonThemeDark2	暗色主题（变体）	对比度更高的暗色需求

主题API摘要

方法 / 属性	所属类	说明
setRibbonTheme(SARibbonTheme)	SARibbonMainWindow / SARibbonWidget	设置Ribbon主题
ribbonTheme() → SARibbonTheme	SARibbonMainWindow / SARibbonWidget	获取当前主题
Q_PROPERTY(ribbonTheme)	SARibbonMainWindow / SARibbonWidget	主题属性，可通过QSS或代码绑定

构造函数中设置主题的时机

某些Qt版本在构造函数中直接调用 setRibbonTheme() 可能不完全生效，原因是QSS在构造阶段尚未完全加载。推荐使用 QTimer::singleShot(0) 将主题设置延迟到事件循环开始后执行。

动态切换主题示例

以下代码演示如何通过一个 ComboBox 动态切换主题（参考 example/MainWindowExample）：

void MainWindow::onThemeChanged(int index)
{
    SARibbonTheme theme = static_cast<SARibbonTheme>(index);
    setRibbonTheme(theme);
    // 如果程序有自定义的QSS，需要在设置主题后再叠加
    if (!m_customStyleSheet.isEmpty()) {
        // setRibbonTheme会自动应用内置主题QSS，setStyleSheet会叠加自定义QSS
        // 注意：setStyleSheet追加的内容不会覆盖之前由setRibbonTheme设置的样式
        this->setStyleSheet(m_customStyleSheet);
    }
}

QSS合并说明

SARibbon的主题是通过QSS实现的。如果你的窗口已经存在QSS样式，需要将你的QSS样式和Ribbon的QSS样式进行合并，否则后设置的样式会覆盖之前的样式。

合并方法：

// 方法一：先设置内置主题，再叠加自定义QSS
// setRibbonTheme会自动应用内置主题的QSS到窗口
setRibbonTheme(SARibbonTheme::RibbonThemeOffice2021Blue);
// 之后追加自定义QSS（setStyleSheet会叠加，不会覆盖内置主题QSS）
this->setStyleSheet(loadMyCustomStyleSheet());

// 方法二：如果你不需要内置主题，完全使用自定义QSS
// 参考 example/MatlabUI 的实现方式
QFile file(":/theme/my-theme.qss");
if (file.open(QIODevice::ReadOnly | QIODevice::Text)) {
    this->setStyleSheet(QString::fromUtf8(file.readAll()));
}

注意

sa_get_ribbon_theme_qss 函数在早期文档中被提及，但该函数不存在于当前代码库中。获取内置主题QSS的唯一方式是通过 setRibbonTheme() 自动应用，没有公共API可以直接获取主题QSS字符串。

提示

内置主题的QSS文件位于 src/SARibbonBar/resource 目录，你可以直接参考这些文件来编写自定义主题。如果需要完全自定义主题，请参阅 自定义Ribbon主题。