创建Ribbon界面¶

Category（分类页）: Ribbon 界面的顶层标签页，通过 addCategoryPage 创建和管理
Panel（面板）: Category 下的功能分组容器，支持 Large/Medium/Small 三种按钮占位模式
菜单按钮: 支持 DelayedPopup、MenuButtonPopup、InstantPopup 三种弹出模式
按钮组（ButtonGroup）: 继承 QToolBar，将多个小按钮紧密排列，适合文本对齐等相近功能
Gallery（画廊）: Ribbon 特有控件，以网格形式展示带图标的选项，如 Word 的样式选择器
Context Category（上下文标签页）: 按需显示/隐藏的特殊标签页，如选中图片时出现的"图片工具"
Application Button: 左上角主菜单按钮，支持自定义 QSS 样式和垂直扩展
Application Widget: 全屏/半屏弹出式窗口，实现类似 Office 的文件操作界面
Quick Access Bar: 窗口顶部的快速访问工具栏，放置保存、撤销等常用操作
Right Button Group / Window Button Bar: 右侧功能按钮组和系统标题栏按钮旁的自定义工具栏

文档导航¶

本文档较长，您可以根据需要直接跳转到对应章节：

章节	内容概要	适合场景
Ribbon组件创建流程	组件层级关系和创建顺序总览	首次了解整体架构
Category（分类页）	创建和管理标签页	添加"主页""插入"等标签
Panel（面板）	面板创建、按钮添加、菜单弹出模式、布局占位、嵌入控件	组织功能按钮和菜单
按钮组（Button Group）	紧密排列的小按钮组	文本对齐、格式切换等
Gallery（画廊）	网格图标选项控件	样式选择器、模板列表
Context Category	按条件显示的上下文标签页	图片工具、表格工具
Application Button	左上角主菜单按钮	文件菜单、自定义 QSS
Application Widget	全屏弹出式应用窗口	类似 Office 的文件操作页
Quick Access Bar	顶部快速访问工具栏	保存、撤销、搜索框
Right Button Group / Window Button Bar	右侧按钮组和系统按钮栏	帮助、登录、设置按钮
SARibbonMenu / GalleryGroup / GalleryItem	详细 API 参考	查阅具体接口用法

Ribbon组件创建流程¶

从获取 SARibbonBar 到创建各类 UI 元素，遵循以下层级递进的创建流程：

flowchart LR
    A[获取 SARibbonBar] --> B[创建 SARibbonCategory]
    B --> C[创建 SARibbonPanel]
    C --> D{选择组件类型}
    B -->|上下文标签| J[addContextCategory + addCategoryPage]
    A --> K[配置 QuickAccessBar]
    A --> L[配置 RightButtonGroup]
    A --> M[配置 ApplicationButton]
    J --> N[showContextCategory/hideContextCategory]

Category(分类页)¶

创建分类页有两种方式：

方式一：通过ribbonbar添加

SARibbonBar* ribbon = ribbonBar();
// 直接添加一个名为“Main”的分类页
SARibbonCategory* homeCategory = ribbon->addCategoryPage("Main");
// 如果你需要进行ribbon界面自定义配置工具（SARibbonCustomizeDialog），你必须设置 objectName用于区分
homeCategory->setObjectName("MainCategory");

上面的代码将会添加一个名字为Main的标签页

add-category

方式二：先创建后添加

// 先创建一个分类页对象
SARibbonCategory* insertCategory = new SARibbonCategory(this);
insertCategory->setCategoryName("插入");
insertCategory->setObjectName("insertCategory");

// 再将其添加到 RibbonBar
ribbon->addCategoryPage(insertCategory);

Panel(面板)¶

创建面板并添加动作¶

面板是category下面的一组功能。您可以通过 Category 的 addPanel 方法创建面板，并通过 addAction 系列方法添加功能按钮

每个category必须有一个panel

// 在 "主页" 分类下创建一个 "文件" 面板
SARibbonPanel* filePanel = homeCategory->addPanel("文件");
filePanel->setObjectName("filePanel");

// 创建动作
QAction* newAction = new QAction(QIcon(":/new.svg"), "新建", this);
newAction->setObjectName("action_new");
newAction->setShortcut(QKeySequence::New);

// 将动作添加到面板
// addLargeAction: 大按钮，图标+文字
filePanel->addLargeAction(newAction);
// addSmallAction: 小按钮，通常只有图标
QAction* saveAction = new QAction(QIcon(":/save.svg"), "保存", this);
saveAction->setObjectName("action_save");
filePanel->addSmallAction(saveAction);

// 连接信号槽
connect(newAction, &QAction::triggered, [] {
    qDebug() << "New document created.";
});

创建菜单¶

在 Ribbon 界面中，菜单（Menu）是组织复杂功能的重要手段。SARibbon允许您将菜单以不同风格的按钮形式添加到面板中。主要区别在于按钮的弹出模式 (QToolButton::ToolButtonPopupMode)，它决定了用户如何与菜单进行交互

SARibbon 支持3种主要的弹出模式，您可以根据功能需求选择最合适的模式：

DelayedPopup (延迟弹出):

用户点击按钮，会执行按钮的默认动作,用户长按按钮，菜单才会弹出（长按直至菜单弹出，按钮的默认动作不会执行）。适用场景主要是当按钮的主要功能是执行一个常用操作，菜单提供的是次要或高级选项时才选用此模式
MenuButtonPopup (菜单按钮弹出)：

这是 Ribbon 界面最具特色的模式。按钮会被视觉上分割为上下两部分，点击按钮的上半部分（图标区域）会执行默认动作；点击下半部分（文本或下拉箭头区域）则会直接弹出菜单，不执行默认动作。鼠标悬停时，两部分会有不同的高亮效果。

这是最推荐的模式，尤其适用于 Office 风格的应用。它清晰地区分了主要操作和次要操作，用户体验最佳。例如，一个“粘贴”按钮，点击图标区域执行标准粘贴，点击下拉箭头区域则弹出“选择性粘贴”、“粘贴为纯文本”等选项。
InstantPopup (即时弹出)：

用户点击按钮的任何部分，都会立即弹出菜单，不会执行按钮的默认动作。这种模式适用于当按钮的功能完全由其下拉菜单定义，没有单一的“默认”操作时。例如，“页面布局”按钮，点击后直接弹出设置页边距、纸张方向等选项的菜单。

SARibbon添加菜单有两种方法，第一种是调用addXXAction函数：

// 把action加入到panel，并以小图标显示
void addSmallAction(QAction* action, QToolButton::ToolButtonPopupMode popMode);
// 把action加入到panel，并以大图标显示
void addLargeAction(QAction* action, QToolButton::ToolButtonPopupMode popMode);
// 把action加入到panel，在三行模式下会以中图标显示
void addMediumAction(QAction* action, QToolButton::ToolButtonPopupMode popMode);

使用这种方法是action包含了menu，第二个参数明确指定了按钮的样式

下面是使用此方法的例子：

SARibbonPanel* panelToolButtonStyle = page->addPanel(("sa ribbon toolbutton style"));

QMenu* menu = new QMenu;
//...构建菜单

// DelayedPopup模式
QAction* act = createAction(tr("Delayed\nPopup"), ":/icon/icon/folder-cog.svg");
act->setMenu(menu);
panelToolButtonStyle->addLargeAction(act, QToolButton::DelayedPopup);
connect(act, &QAction::triggered, this, &MainWindow::onDelayedPopupTriggered);

act = createAction(tr("Menu Button Popup"), ":/icon/icon/folder-star.svg");
act->setMenu(menu);
panelToolButtonStyle->addLargeAction(act, QToolButton::MenuButtonPopup);
connect(act, &QAction::triggered, this, &MainWindow::onMenuButtonPopupTriggered);

act = createAction(tr("Instant Popup"), ":/icon/icon/folder-stats.svg");
act->setMenu(menu);
panelToolButtonStyle->addLargeAction(act, QToolButton::InstantPopup);
connect(act, &QAction::triggered, this, &MainWindow::onInstantPopupTriggered);

上面的代码将会创建如下三个菜单按钮

SARibbon-Toolbutton-Style

这三个按钮共享一个菜单

SARibbon还提供了另外一个接口来快速添加菜单(方法位于SARibbonPanel类)：

// 添加menu
void addMenu(QMenu* menu,
                SARibbonPanelItem::RowProportion rowProportion,
                QToolButton::ToolButtonPopupMode popMode = QToolButton::InstantPopup);
// 添加普通大菜单
void addLargeMenu(QMenu* menu, QToolButton::ToolButtonPopupMode popMode = QToolButton::InstantPopup);
// 添加中等尺寸菜单按钮
void addMediumMenu(QMenu* menu, QToolButton::ToolButtonPopupMode popMode = QToolButton::InstantPopup);
// 添加普通小按钮菜单
void addSmallMenu(QMenu* menu, QToolButton::ToolButtonPopupMode popMode = QToolButton::InstantPopup);

这几个函数实际利用率menu自身的action进行管理，无需再单独创建一个action

注意

这几个方法会修改 menu->menuAction() 的部分属性（icon/text/objectName），如需保留自定义值，请提前设置。

面板的布局占位说明¶

SARibbon 面板的布局目前有3种占位标志。当您调用 addLargeAction、addMediumAction 或 addSmallAction 时，您不仅是在添加一个按钮，还在指定它在网格布局中的"占位大小"。

Large Action: 高度上占据2行或3行（取决于当前是两行还是三行模式），显示大图标和文字。
Medium Action: 高度上占据1行或1.5行的网格（取决于当前是两行还是三行模式），通常显示图标和文字。
Small Action: 高度上占据1行

这些行占比在不同的布局方案会有不同的呈现效果

SARibbonPanel支持三种布局方案，分别是3行模式、2行模式和单行模式（v2.8.0 新增），通过SARibbonBar::setRibbonStyle函数你可以设置不同的布局风格

对于3行模式，上诉三种行占位的效果如下图所示

pannelLayout3row

对于2行模式，上诉三种行占位的效果如下图所示

pannelLayout2row

2行模式下medium和small占位(SARibbonPanelItem::RowProportion)是一样的，不做区分。

对于单行模式（v2.8.0 新增），所有按钮排列在同一行内，图标在左侧、文字在右侧横向排列，Large、Medium、Small 占位都等效为 Small。建议搭配 SARibbonBar::setEnableIconRightText(true) 使用。

关于面板按钮的布局，详细可见：Ribbon栏按钮布局说明，以及：SARibbon布局方式

面板犹如一个Toolbar,添加的action最终会以按钮的方式进行渲染，SARibbonBar的提供了许多函数可以统一设置面板的属性：

设置panel按钮图标尺寸：

// 大按钮图标尺寸
void setPanelLargeIconSize(const QSize& largeSize);
// 小按钮图标尺寸
void setPanelSmallIconSize(const QSize& smallSize);

设置panel的一些渲染属性：

// 设置按钮是否允许换行
void setEnableWordWrap(bool on);
// 设置panel是否显示标题栏
void setEnableShowPanelTitle(bool on);

设置panel的一些位置尺寸：

// 设置panel与panel之间的间距
void setPanelSpacing(int n);
// 设置panel的标题栏高度
void setPanelTitleHeight(int h);
// 按钮的最大宽高比，这个系数决定按钮的最大宽度，系数越大，按钮能显示的越宽
void setButtonMaximumAspectRatio(qreal fac = 1.4);

上面的方法会作用到每一个已经设置的panel和对应的按钮

除了 QAction，您还可以直接在面板中添加任何 QWidget，例如组合框、微调框或自定义控件。

SARibbonCategory* page = ribbonBar()->addCategoryPage(tr("Main"));
SARibbonPanel* panelWidgetTest = page->addPanel(tr("widget test"));

QComboBox* com1 = new QComboBox(this);
com1->setWindowTitle(tr("QComboBox test"));
for (int i = 0; i < 40; ++i) {
    com1->addItem(QString("QComboBox test%1").arg(i + 1));
}
com1->setEditable(true);
panelWidgetTest->addSmallWidget(com1);

QComboBox* com2 = new QComboBox(this);
com2->setWindowTitle("ComboBox Editable");
for (int i = 0; i < 40; ++i) {
    com2->addItem(QString("item %1").arg(i + 1));
}
panelWidgetTest->addSmallWidget(com2);


QLineEdit* lineEdit = new QLineEdit(this);
lineEdit->setText("LineEdit");
panelWidgetTest->addSmallWidget(lineEdit);

panelWidgetTest->addSeparator();

QCalendarWidget* calendarWidget = new QCalendarWidget(this);
panelWidgetTest->addLargeWidget(calendarWidget);

上面代码的效果如下：

使用按钮组 (Button Group)¶

按钮组SARibbonButtonGroupWidget 可以将多个小按钮紧密排列在一起，和QToolBar类似，常用于一组相近功能的操作，如文本对齐

SARibbonButtonGroupWidget继承QToolBar，在一个按钮组里的action,你不需要再组个aciton绑定信号，使用QToolBar::actionTriggered信号即可

下面这段代码演示如何创建按钮组，以及如何绑定信号

// 按钮组2
SARibbonButtonGroupWidget* btnGroup2 = new SARibbonButtonGroupWidget(panel1);
btnGroup2->setObjectName("SARibbonButtonGroupWidget2");

QAction* titleAlgnmentRight = createAction(tr("Align Right"), ":/icon/icon/Align-Right.svg");
titleAlgnmentRight->setProperty("align", (int)Qt::AlignRight | Qt::AlignVCenter);
btnGroup2->addAction(titleAlgnmentRight);
QAction* titleAlgnmentLeft = createAction(tr("Align Left"), ":/icon/icon/Align-Left.svg");
titleAlgnmentLeft->setProperty("align", (int)Qt::AlignLeft | Qt::AlignVCenter);
btnGroup2->addAction(titleAlgnmentLeft);
QAction* titleAlgnmentCenter = createAction(tr("Align Center"), ":/icon/icon/Align-Center.svg");
titleAlgnmentCenter->setProperty("align", (int)Qt::AlignCenter);
btnGroup2->addAction(titleAlgnmentCenter);
panel1->addWidget(btnGroup2, SARibbonPanelItem::Medium);
connect(btnGroup2, &SARibbonButtonGroupWidget::actionTriggered, this, &MainWindow::onButtonGroupActionTriggered);

上面的代码生成了如下界面（具体例子可见example/MainWindowExample/mainWindow.cpp,createCategoryOther函数）

使用Gallery(画廊)¶

Gallery (画廊)是一个Ribbon特有的控件，用于以网格形式展示带图标的选项，常用于在有限空间显示大量图标动作，例如word的样式选择

SARibbon的Gallery (画廊)对应窗口为SARibbonGallery，通过SARibbonPanel::addGallery即可创建一个Gallery (画廊)，此函数返回创建的SARibbonGallery指针

SARibbonGallery可以管理多个动作组，一个动作组对应的类名为SARibbonGalleryGroup,你可以使用SARibbonGallery::addCategoryActions方法快速添加动作组，其参数是动作组标题和动作组的action列表

SARibbonGalleryGroup* addCategoryActions(const QString& title, QList< QAction* > actions);

下面这段代码演示了如何创建一个Gallery (画廊)，并添加2个动作组

QAction MyRibbonMainWindow::createAction(const QString& text, const QString& iconurl){
    QAction* act = new QAction(this);
    act->setText(text);
    act->setIcon(QIcon(iconurl));
    return act;
}

void MyRibbonMainWindow::buildGalleryExample(){
    SARibbonPanel* panelWithGallery = ...;
    ...
    // 创建一个Gallery (画廊)
    SARibbonGallery* gallery = panelWithGallery->addGallery();
    // 添加动作组1
    QList< QAction* > galleryActions1;
    galleryActions1.append(createAction("Document File", ":/gallery-icon/icon/gallery/Document-File.svg"));
    galleryActions1.append(createAction("Download File", ":/gallery-icon/icon/gallery/Download-File.svg"));
    ......
    galleryActions1.append(createAction("File Settings", ":/gallery-icon/icon/gallery/File-Settings.svg"));
    galleryActions1.append(createAction("Presentation File", ":/gallery-icon/icon/gallery/Presentation-File.svg"));
    SARibbonGalleryGroup* group1 = gallery->addCategoryActions(tr("Files"), galleryActions1);
    group1->setGalleryGroupStyle(SARibbonGalleryGroup::IconWithWordWrapText);
    group1->setGridMinimumWidth(80);

    // 添加动作组2
    QList< QAction* > galleryActions2;
    galleryActions2.append(createAction("Photoshop", ":/gallery-icon/icon/gallery/Photoshop.svg"));
    galleryActions2.append(createAction("Internet-Explorer", ":/gallery-icon/icon/gallery/Internet-Explorer.svg"));
    galleryActions2.append(createAction("Illustrator", ":/gallery-icon/icon/gallery/Illustrator.svg"));
    galleryActions2.append(createAction("Google-Maps", ":/gallery-icon/icon/gallery/Google-Maps.svg"));
    galleryActions2.append(createAction("Adobe", ":/gallery-icon/icon/gallery/Adobe.svg"));
    galleryActions2.append(createAction("Word", ":/gallery-icon/icon/gallery/Word.svg"));
    SARibbonGalleryGroup* group2 = gallery->addCategoryActions(tr("Apps"), galleryActions2);
    group2->setGridMinimumWidth(80);
    // 设置当前显示的组
    gallery->setCurrentViewGroup(group1);
}

通过上面代码，创建的gallery效果如下:

saribbon-gallery

此gallery展开后效果如下：

Context Category(上下文标签页)¶

Context Category 是一种特殊标签页，通常在特定条件下（如选中某个对象）才显示，最常见的就是word中的“图片工具”和“表格工具”，是在选中图片或表格时才出现，这种有条件显示的标签称之为上下文标签

SARibbon的Context Category(上下文标签页)对应窗口为SARibbonContextCategory，通过SARibbonBar::addContextCategory即可创建一个Context Category(上下文标签页)，此函数返回创建的SARibbonContextCategory指针

SARibbonContextCategory并不是一个窗口(它的基类是QObject)，只是一个标签页管理器，需要再SARibbonContextCategory上添加标签页，通过SARibbonContextCategory::addCategoryPage方法即可在对应的Context Category(上下文标签页)上添加标签页

Context Category(上下文标签页)默认情况下不会显示，需要调用SARibbonBar::showContextCategory方法显示，隐藏上下文标签页则可通过SARibbonBar::hideContextCategory实现，SARibbonContextCategory也带有show/hide槽函数来实现上下文标签页的显示和隐藏

下面这段代码演示了如何创建一个Context Category(上下文标签页)，并添加两个标签页

//m_contextCategory为MainWindow的成员变量：SARibbonContextCategory* m_contextCategory;

void MainWindow::createContextCategory(){
    SARibbonBar* ribbon = ribbonBar();
    m_contextCategory    = ribbon->addContextCategory(tr("context"), QColor(), 1);

    SARibbonCategory* contextCategoryPage1 = m_contextCategory->addCategoryPage(tr("Page1"));
    //创建contextCategoryPage1对应的内容
    createContextCategoryPage1(contextCategoryPage1);

    SARibbonCategory* contextCategoryPage2 = m_contextCategory->addCategoryPage(tr("Page2"));
    //创建contextCategoryPage2对应的内容
    createContextCategoryPage2(contextCategoryPage2);
}

上面的代码创建完Context Category(上下文标签页)后并不会显示，如果需要显示，你还需在特定条件下触发

void MainWindow::onShowContextCategory(bool on)
{
    if (m_contextCategory == nullptr) {
        createContextCategory();
    }
    if (on) {
        m_contextCategory->show();
    } else {
        m_contextCategory->hide();
    }
}

上面的代码效果如下：

SARibbonBar-Context-Category

为了区分上下文标签页和普通的标签页，上下文标签页会有特殊的颜色进行标识，如上图所示。这个标识的颜色可以通过SARibbonBar::setContextCategoryColorList设置

Application Button¶

Application Button 是 Ribbon 界面左上角的主菜单按钮，通常用于“文件”操作

SARibbon 在创建 SARibbonBar 时，会默认创建一个SARibbonApplicationButton实例作为Application Button。您可以通过 SARibbonBar::applicationButton方法获取该按钮的指针，并对其进行操作，例如设置文本、设置图标、设置快捷键、设置菜单，等等

如：

void MainWindow::createRibbonApplicationButton()
{
    SARibbonBar* ribbon = ribbonBar();
    QAbstractButton* btn = ribbon->applicationButton();
    btn->setText(("&File"));

    SARibbonApplicationButton* appBtn = qobject_cast< SARibbonApplicationButton* >(btn);
    if (appBtn) {
        QMenu* menu = new QMenu(this);
        ...
        appBtn->setMenu(menu);
    }
}

如果你有自定义的按钮，你可以通过 SARibbonBar::setApplicationButton 方法设置 Application Button。如果你不想要Application Button，你可以传入nullptr

ribbonBar()->setApplicationButton(nullptr); // 移除按钮

application button可以通过qss设置比较丰富的样式，下面是模仿win7风格的ribbon样式设置的qss演示：

SARibbonApplicationButton{
  color:white;
  border: 1px solid #416ABD;
  border-top-left-radius: 4px;
  border-top-right-radius: 4px;
  background-color: qlineargradient(spread:pad, x1:0, y1:0, x2:0, y2:1,stop:0 #467FBD, stop:0.5 #2A5FAC,stop:0.51 #1A4088,
stop:1 #419ACF);
}

SARibbonApplicationButton:hover{
  background-color: qlineargradient(spread:pad, x1:0, y1:0, x2:0, y2:1,stop:0 #7BB2EB, stop:0.5 #477ECD,stop:0.51 #114ECF,
stop:1 #80E1FF);
}

SARibbonApplicationButton:pressed{
  background-color: qlineargradient(spread:pad, x1:0, y1:0, x2:0, y2:1,stop:0 #467BBB, stop:0.5 #2F63AE,stop:0.51 #1C438A,
stop:1 #358BC9);
}

SARibbonApplicationButton:focus{
  outline: none;
}

SARibbonApplicationButton::menu-indicator {
  /*subcontrol-position: right;*/
  width:0px;
}

上面的效果如下：

在宽松模式下，Application Button可以设置为垂直扩展，这时候，Application Button将占用标题栏和tab栏的空间

示例：

ribbonBar()->setApplicationButtonVerticalExpansion(true);

上面的代码效果如图所示：

注意

SARibbonBar::setApplicationButtonVerticalExpansion函数会对titleIconWidget的可见性进行调整，如果设置applicationButtonVerticalExpansion=true，那么titleIconWidget会被隐藏，反之，titleIconWidget会被显示
但SARibbonBar::setTitleIconVisible函数不会对applicationButtonVerticalExpansion的状态有影响
因此，如果你动态调整applicationButtonVerticalExpansion的状态，如果你需要显示窗口图标，在设置setApplicationButtonVerticalExpansion(false)后，需要调用setTitleIconVisible(true)让窗口图标显示

注意

ApplicationButtonVerticalExpansion仅在宽松模式(SARibbonBar::RibbonStyleLoose)下有效

在许多现代化应用（如 Microsoft Office）中，点击 Application Button 并不会弹出一个简单的下拉菜单，而是会弹出一个全屏或半屏的复杂页面，该页面可以包含最近文件列表、模板选择、账户设置、应用选项等丰富内容

SARibbon提供了SARibbonApplicationWidget，它能自动帮你覆盖主窗口，你的弹出式窗口可以继承SARibbonApplicationWidget来实现

SARibbonApplicationWidget提供了resizeToParent函数来决定如何相对父窗口进行缩放，默认是完全覆盖父窗口，如果你想覆盖一半或者其他尺寸，你可以重写此函数

API摘要¶

方法名	返回值	说明
`SARibbonApplicationWidget(SARibbonMainWindow* parent)`	构造	创建应用窗口控件
`resizeToParent(const QSize& parentSize)`	void	相对父窗口缩放（可重写）
`eventFilter(QObject, QEvent)`	bool	过滤父窗口事件
`showEvent(QShowEvent*)`	void	处理显示事件
`keyPressEvent(QKeyEvent*)`	void	处理键盘事件（ESC关闭）

使用Application Widget的例子如下：

继承SARibbonApplicationWidget实现自己的窗口

class ApplicationWidget : public SARibbonApplicationWidget
{
    Q_OBJECT
public:
    explicit ApplicationWidget(SARibbonMainWindow* parent = nullptr);
    ~ApplicationWidget();
};

在MainWindow中创建Application Widget的成员变量指针m_appWidget，初始化时绑定applicationButton的响应：

void MainWindow::createRibbonApplicationButton()
{
    SARibbonBar* ribbon = ribbonBar();
    if (!ribbon) {
        return;
    }
    QAbstractButton* btn = ribbon->applicationButton();
    btn->setText(("&File"));
    // 这里演示用SARibbonApplicationWidget实现一个类似office的弹出式窗口
    m_appWidget = new ApplicationWidget(this);
    m_appWidget->hide();
    connect(btn, &QAbstractButton::clicked, this, [ this ](bool c) {
        Q_UNUSED(c);
        this->m_appWidget->show();
    });
}

上面的代码效果如下：

Quick Access Bar（快速访问工具栏）¶

快速访问工具栏位于窗口最顶部，用于放置最常用的操作，如保存、撤销、重做。快速访问工具栏对应的类为SARibbonQuickAccessBar,它继承自QToolBar，你可以和操作工具栏一样使用它

SARibbon默认会创建一个快速访问工具栏，你可以调用SARibbonBar::quickAccessBar函数获取快速访问工具栏的指针，然后对快速访问工具栏进行操作

下面是快速访问工具栏的用法：

void MainWindow::createQuickAccessBar()
{
    SARibbonQuickAccessBar* quickAccessBar = ribbonBar()->quickAccessBar();

    QAction* actionSave = new QAction(QIcon(":/icon/icon/save.svg"),"save",this);
    quickAccessBar->addAction(actionSave);
    quickAccessBar->addSeparator();

    QAction* actionUndo = new QAction(QIcon(":/icon/icon/undo.svg"),"undo",this);
    quickAccessBar->addAction(actionUndo);

    QAction* actionRedo = new QAction(QIcon(":/icon/icon/redo.svg"),"redo",this);
    quickAccessBar->addAction(actionRedo);

    quickAccessBar->addSeparator();

    QMenu* menu1 = new QMenu("Presentation File 1", this);
    menu1->setIcon(QIcon(":/icon/icon/presentationFile.svg"));
    // 创建菜单
    ...
    // 创建 QAction
    quickAccessBar->addMenuAction(menu1->menuAction());//效果等同quickAccessBar->addMenuAction(menu1);

    QMenu* menu2 = new QMenu("Presentation File 2", this);
    menu2->setIcon(QIcon(":/icon/icon/presentationFile.svg"));
    // 创建菜单
    ...
    quickAccessBar->addMenuAction(menu2, QToolButton::MenuButtonPopup);
    ...
    mSearchEditor = new QLineEdit(this);
    mSearchEditor->setMinimumWidth(150);
    mSearchEditor->setPlaceholderText("Search");
    quickAccessBar->addWidget(mSearchEditor);
}

上面的代码创建了一个快速访问工具栏，效果如下：

quick-access-bar

Right Button Group（右侧按钮组）¶

Right Button Group（右侧按钮组）是 Ribbon 界面右上角按钮组，通常用于“帮助”、“设置”、“关于”等操作。Right Button Group（右侧按钮组）对应的类为SARibbonButtonGroupWidget,它继承自QToolBar，你可以和操作工具栏一样使用它

SARibbon默认会创建一个Right Button Group（右侧按钮组），你可以调用SARibbonBar::rightButtonGroup函数获取Right Button Group的指针，然后对它进行操作

下面是Right Button Group的用法：

void MainWindow::createRightButtonGroup()
{
    SARibbonBar* ribbon = ribbonBar();
    SARibbonButtonGroupWidget* rightBar = ribbon->rightButtonGroup();
    QAction* actionHelp                 = new QAction(QIcon(":/icon/icon/help.svg"),"help",this);
    QAction* actionVisible                   = new QAction(QIcon(":/icon/icon/visible-true.svg"),"Visible",this);
    rightBar->addAction(actionHelp);
    rightBar->addAction(actionVisible);
}

Right Button Group（右侧按钮组）效果如下：

Window Button Bar（系统标题栏按钮旁的工具栏）¶

Window Button Bar（系统标题栏按钮旁的工具栏）是 Ribbon 界面系统最大最小化合关闭按钮组，Window Button Bar对应的类名为SARibbonSystemButtonBar，它默认会创建好窗口需要的最大最小化及关闭按钮，它会自动处理窗口的状态调整系统按钮的显示，SARibbonSystemButtonBar内部有一个SARibbonButtonGroupWidget，提供了addAction、addSeparator、addWidget等函数，用于在最大最小化旁边添加按钮

你可以通过SARibbonMainWindow的windowButtonBar函数获取SARibbonSystemButtonBar指针

注意

SARibbonSystemButtonBar不是SARibbonBar的子窗口，是SARibbonMainWindow的子窗口

SARibbonSystemButtonBar的使用示例如下：

void MainWindow::createWindowButtonGroupBar()
{
    SARibbonSystemButtonBar* wbar = windowButtonBar();
    if (!wbar) {
        return;
    }
    QAction* actionLogin = new QAction(QIcon(), "Login",this);
    QAction* actionHelp = new QAction(QIcon(":/icon/icon/help.svg"),"help",this);
    ...
    wbar->addAction(a);
    wbar->addAction(actionHelp);
}

上面代码的效果如下：

SARibbonMenu 详细用法¶

SARibbonMenu 是专为 Ribbon 界面设计的菜单类，继承自 QMenu。它可以通过 StyleSheet 独立设置样式而不影响全局的 QMenu 样式，适合在 Ribbon 环境中使用。

与 QMenu 的区别¶

特性	QMenu	SARibbonMenu
样式隔离	通过 QSS 会影响所有 QMenu	仅影响 SARibbonMenu 实例
子菜单类型	返回普通 QMenu	返回 SARibbonMenu
控件支持	支持 addWidget	提供 addWidget 方法

API摘要¶

方法名	返回值	说明
`SARibbonMenu(QWidget* parent)`	构造	创建空菜单
`SARibbonMenu(const QString& title, QWidget* parent)`	构造	创建带标题的菜单
`addRibbonMenu(SARibbonMenu* menu)`	`QAction*`	添加已存在的 SARibbonMenu 作为子菜单
`addRibbonMenu(const QString& title)`	`SARibbonMenu*`	创建并添加指定标题的子菜单
`addRibbonMenu(const QIcon& icon, const QString& title)`	`SARibbonMenu*`	创建并添加带图标和标题的子菜单
`addWidget(QWidget* w)`	`QAction*`	向菜单中添加自定义控件

代码示例¶

// 创建 SARibbonMenu
SARibbonMenu* mainMenu = new SARibbonMenu(tr("文件操作"), panel);

// 添加普通动作
mainMenu->addAction("新建");
mainMenu->addAction("打开");
mainMenu->addSeparator();

// 添加子菜单（使用 addRibbonMenu）
SARibbonMenu* recentSubmenu = mainMenu->addRibbonMenu(tr("最近文件"));
recentSubmenu->addAction("document1.docx");
recentSubmenu->addAction("document2.docx");

// 添加带图标的子菜单
SARibbonMenu* exportSubmenu = mainMenu->addRibbonMenu(
    QIcon(":/icon/export.svg"), tr("导出"));
exportSubmenu->addAction("PDF");
exportSubmenu->addAction("HTML");

// 添加自定义控件到菜单
QLabel* label = new QLabel(tr("自定义内容"));
label->setStyleSheet("padding: 8px;");
mainMenu->addWidget(label);

// 将菜单关联到面板按钮
actionExport->setMenu(mainMenu);
panel->addLargeAction(actionExport, QToolButton::MenuButtonPopup);

SARibbonGalleryGroup API 详解¶

SARibbonGalleryGroup 是 Gallery 控件中的动作组，继承自 QListView，负责以网格形式显示和管理一组 SARibbonGalleryItem。

枚举类型¶

GalleryGroupStyle 显示样式¶

枚举值	说明
`IconWithText`	图标+文字（文字在一行显示）
`IconWithWordWrapText`	图标+自动换行文字（仅在 DisplayOneRow 下生效）
`IconOnly`	仅显示图标

DisplayRow 显示行数¶

枚举值	说明
`DisplayOneRow` (1)	显示1行（默认）
`DisplayTwoRow` (2)	显示2行
`DisplayThreeRow` (3)	显示3行

API摘要¶

方法名	返回值	说明
`setGalleryGroupStyle(GalleryGroupStyle)`	void	设置显示样式
`galleryGroupStyle()`	`GalleryGroupStyle`	获取当前显示样式
`setDisplayRow(DisplayRow)`	void	设置显示行数
`displayRow()`	`DisplayRow`	获取当前显示行数
`setGridMinimumWidth(int)`	void	设置网格最小宽度（默认0:不限制）
`gridMinimumWidth()`	int	获取网格最小宽度
`setGridMaximumWidth(int)`	void	设置网格最大宽度（默认0:不限制）
`gridMaximumWidth()`	int	获取网格最大宽度
`addItem(const QString&, const QIcon&)`	void	添加项
`addItem(SARibbonGalleryItem*)`	void	添加项对象
`addActionItem(QAction*)`	void	将 QAction 添加为项
`addActionItemList(const QList<QAction*>&)`	void	批量添加 QAction
`removeActionItem(QAction*)`	bool	移除指定 QAction 项
`setGroupTitle(const QString&)`	void	设置组标题
`groupTitle()`	QString	获取组标题
`groupModel()`	`SARibbonGalleryGroupModel*`	获取底层模型
`actionGroup()`	`QActionGroup*`	获取管理的 QActionGroup
`gridRowCount()`	int	获取网格行数
`gridColumnCount()`	int	获取网格列数
`selectByIndex(int)`	void	按索引选中项
`recalcGridSize()`	void	重新计算网格大小
`preferredHeightForWidth(int)`	int	获取指定宽度的推荐高度

代码示例¶

// 创建 Gallery Group 并设置样式
SARibbonGalleryGroup* group = gallery->addCategoryActions(tr("样式"), actions);
group->setGalleryGroupStyle(SARibbonGalleryGroup::IconWithWordWrapText);
group->setDisplayRow(SARibbonGalleryGroup::DisplayTwoRow);
group->setGridMinimumWidth(80);
group->setGridMaximumWidth(120);

// 响应触发信号
connect(group, &SARibbonGalleryGroup::triggered, this, [](QAction* act) {
    qDebug() << "Selected:" << act->text();
});

// 监听悬停信号（需启用鼠标跟踪）
group->setMouseTracking(true);
connect(group, &SARibbonGalleryGroup::hovered, this, [](QAction* act) {
    qDebug() << "Hovered:" << act->text();
});

SARibbonGalleryItem 用法¶

SARibbonGalleryItem 是 Gallery 中的单个数据项，类似 QStandardItem，用于设置图标、文字、关联动作等数据。

API摘要¶

方法名	返回值	说明
`SARibbonGalleryItem()`	构造	创建空项
`SARibbonGalleryItem(const QString&, const QIcon&)`	构造	创建带文字和图标的项
`SARibbonGalleryItem(QAction*)`	构造	从 QAction 创建
`setText(const QString&)`	void	设置文字
`text()`	QString	获取文字
`setToolTip(const QString&)`	void	设置工具提示
`toolTip()`	QString	获取工具提示
`setIcon(const QIcon&)`	void	设置图标
`icon()`	QIcon	获取图标
`setAction(QAction*)`	void	设置关联的动作
`action()`	`QAction*`	获取关联的动作
`setSelectable(bool)`	void	设置是否可选中
`isSelectable()`	bool	是否可选中
`setEnable(bool)`	void	设置是否可用
`isEnable()`	bool	是否可用
`setTextAlignment(Qt::Alignment)`	void	设置文字对齐方式
`textAlignment()`	`Qt::Alignment`	获取文字对齐方式
`setData(int role, const QVariant&)`	void	设置指定角色的数据
`data(int role)`	QVariant	获取指定角色的数据

代码示例¶

// 方式一：直接构造
SARibbonGalleryItem* item1 = new SARibbonGalleryItem(
    tr("标题样式1"), QIcon(":/icons/style1.svg"));
item1->setToolTip(tr("应用标题样式1"));
group->addItem(item1);

// 方式二：从 QAction 创建
QAction* act = new QAction(QIcon(":/icons/style2.svg"), tr("样式2"), this);
SARibbonGalleryItem* item2 = new SARibbonGalleryItem(act);
item2->setTextAlignment(Qt::AlignHCenter | Qt::AlignBottom);
group->addItem(item2);

// 方式三：创建后设置数据
SARibbonGalleryItem* item3 = new SARibbonGalleryItem();
item3->setText(tr("自定义样式"));
item3->setIcon(QIcon(":/icons/style3.svg"));
item3->setToolTip(tr("应用自定义标题样式"));
item3->setSelectable(true);
group->addItem(item3);

SARibbonGalleryViewport 详解¶

SARibbonGalleryViewport 是 SARibbonGallery 弹出时显示所有 GalleryGroup 的视口窗口，继承自 QScrollArea。内部使用垂直布局管理多个 GalleryGroup。

API摘要¶

方法名	返回值	说明
`addWidget(QWidget*)`	void	添加控件（不带标题）
`addWidget(QWidget*, const QString&)`	void	添加控件并设置标题
`titleLabel(QWidget*)`	`QLabel*`	获取控件对应的标题标签
`removeWidget(QWidget*)`	void	移除控件
`galleryGroupList()`	`QList<SARibbonGalleryGroup*>`	获取所有 GalleryGroup
`galleryHeight()`	int	获取 Gallery 高度
`heightHintForWidth(int)`	int	根据宽度获取推荐高度

代码示例¶

// 获取 Viewport 并自定义
SARibbonGalleryViewport* viewport = gallery->getPopupViewPort();
if (viewport) {
    // 修改某个 GalleryGroup 的标题样式
    QLabel* title = viewport->titleLabel(group1);
    if (title) {
        title->setStyleSheet("font-size: 14px; font-weight: bold; color: #333;");
    }

    // 添加自定义控件到 Viewport
    QWidget* customWidget = new QWidget(viewport);
    viewport->addWidget(customWidget, tr("自定义区域"));

    // 移除不需要的控件
    // viewport->removeWidget(someWidget);
}

// 响应展开按钮显示更多
connect(gallery, &SARibbonGallery::triggered, this, [](QAction* act) {
    qDebug() << "Gallery item triggered:" << act->text();
});

SARibbonSystemButtonBar 详细方法¶

SARibbonSystemButtonBar 是窗口标题栏右侧的系统按钮栏，包含最小化、最大化、关闭按钮，并支持添加自定义按钮和控件。

API摘要¶

方法名	返回值	说明
`addAction(QAction*)`	void	添加动作按钮
`addMenuAction(QAction*, popupMode)`	void	添加菜单动作
`addMenuAction(QMenu*, popupMode)`	`QAction*`	添加菜单并返回菜单动作
`addSeparator()`	`QAction*`	添加分隔线
`addWidget(QWidget*)`	`QAction*`	添加自定义控件
`setupMinimizeButton(bool)`	void	设置最小化按钮显隐
`setupMaximizeButton(bool)`	void	设置最大化按钮显隐
`setupCloseButton(bool)`	void	设置关闭按钮显隐
`setButtonWidthStretch(close, max, min)`	void	设置按钮宽度比例
`setWindowTitleHeight(int)`	void	设置标题栏高度
`windowTitleHeight()`	int	获取标题栏高度
`setWindowButtonWidth(int)`	void	设置系统按钮宽度
`windowButtonWidth()`	int	获取系统按钮宽度
`setWindowStates(Qt::WindowStates)`	void	设置窗口状态
`windowButtonFlags()`	`Qt::WindowFlags`	获取按钮标志
`minimizeButton()`	`QAbstractButton*`	获取最小化按钮
`maximizeButton()`	`QAbstractButton*`	获取最大化按钮
`closeButton()`	`QAbstractButton*`	获取关闭按钮
`setIconSize(const QSize&)`	void	设置图标尺寸
`iconSize()`	QSize	获取图标尺寸
`updateWindowFlag()`	void	更新窗口标志

代码示例¶

void MainWindow::setupSystemButtonBar()
{
    SARibbonSystemButtonBar* sysBar = windowButtonBar();
    if (!sysBar) {
        return;
    }

    // 自定义按钮宽度比例
    sysBar->setButtonWidthStretch(4, 3, 3);

    // 添加分隔线
    sysBar->addSeparator();

    // 添加登录按钮
    QAction* loginAction = new QAction(QIcon(":/icon/login.svg"), tr("登录"), this);
    sysBar->addAction(loginAction);
    connect(loginAction, &QAction::triggered, this, &MainWindow::onLogin);

    // 添加带菜单的下拉按钮
    QMenu* themeMenu = new QMenu(tr("主题"), this);
    themeMenu->addAction(tr("浅色"));
    themeMenu->addAction(tr("深色"));
    sysBar->addMenuAction(themeMenu, QToolButton::MenuButtonPopup);

    // 添加自定义控件
    QLabel* statusLabel = new QLabel(tr("在线"), sysBar);
    statusLabel->setStyleSheet("color: green; padding: 0 4px;");
    sysBar->addWidget(statusLabel);

    // 自定义系统按钮图标和尺寸
    sysBar->setIconSize(QSize(16, 16));
}

创建Ribbon界面¶

文档导航¶

Ribbon组件创建流程¶

Category(分类页)¶

Panel(面板)¶

创建面板并添加动作¶

创建菜单¶

面板的布局占位说明¶

在面板中添加复杂控件 (Widget)¶

使用按钮组 (Button Group)¶

使用Gallery(画廊)¶

Context Category(上下文标签页)¶

Application Button¶

Application Widget¶

API摘要¶

Quick Access Bar（快速访问工具栏）¶

Right Button Group（右侧按钮组）¶

Window Button Bar（系统标题栏按钮旁的工具栏）¶

SARibbonMenu 详细用法¶

与 QMenu 的区别¶

API摘要¶

代码示例¶

SARibbonGalleryGroup API 详解¶

枚举类型¶

GalleryGroupStyle 显示样式¶

DisplayRow 显示行数¶

API摘要¶

代码示例¶

SARibbonGalleryItem 用法¶

API摘要¶

代码示例¶

SARibbonGalleryViewport 详解¶

API摘要¶

代码示例¶

SARibbonSystemButtonBar 详细方法¶

API摘要¶

代码示例¶