导航控件

导航控件负责页面切换、命令入口、菜单和滚动定位。它们通常出现在页面顶部、侧栏、工具栏或内容容器边缘。

控件类型

控件	子内容与能力	典型用途
`UIGQTabWidget`	标签项、图标、选中图标、方向、项尺寸和间距	顶部/侧边标签、模块切换
`UIGQMenu`	Action、子菜单、上下文命令、主题外观	右键菜单、命令菜单
`UIGQMenuBar`	顶层菜单、菜单项、窗口命令入口	窗口级菜单栏
`UIGQRibbonBar`	Ribbon 页面、分组、面板、按钮和配置文件	桌面软件命令区、复杂工具栏
`UIGQScrollBar`	方向、范围、滑块、按钮、主题样式	独立滚动条、容器绑定滚动

类继承关系

QWidget
  ├─ UIGQTabWidget + IUIGQWidgetBase
  ├─ QMenu
  │   └─ UIGQMenu + IUIGQWidgetBase
  ├─ QMenuBar
  │   └─ UIGQMenuBar + IUIGQWidgetBase
  ├─ UIGQRibbonBar + IUIGQWidgetBase
  │   ├─ UIGQRibbonArea
  │   ├─ UIGQRibbonPage
  │   ├─ UIGQRibbonGroup
  │   └─ UIGQRibbonPanel
  ├─ QPushButton
  │   └─ UIGQPushButton + IUIGQWidgetBase
  │       └─ UIGQRibbonPushButton
  └─ QScrollBar
      └─ UIGQScrollBar + IUIGQWidgetBase

导航控件组合 Qt 菜单、滚动条和 WidgetKit 自绘容器。Ribbon 内部页面、分组和面板主要负责结构组织，UIGQRibbonBar 和 UIGQRibbonPushButton 负责对外的主题与交互入口。

UIGQTabWidget

UIGQTabWidget 支持横向和纵向标签、图标、选中状态、项间距和项尺寸。

UIGQTabWidget* tabs = new UIGQTabWidget(parent);
tabs->setThemeName("DefaultTabs");
tabs->setIsHor(true);
tabs->setItemSize(96);
tabs->setItemSpace(8);
tabs->addTab("概览", ":/images/home.svg", ":/images/home-on.svg");
tabs->addTab("设置", ":/images/settings.svg", ":/images/settings-on.svg");

connect(tabs, &UIGQTabWidget::currentChanged, this, [stack](int index) {
    stack->setCurrentIndex(index);
});

常用接口：

接口	说明	参数	返回值
`addTab(const QString& text, const QString& icon, const QString& selectedIcon)`	添加标签项。	`text`：文字；`icon`：普通图标；`selectedIcon`：选中图标。	`void`
`setSelectedIndex(int index)`	设置当前选中项。	`index`：目标标签索引。	`void`
`getSelectedIndex() const`	获取当前选中项。	无	`int`
`setIsHor(bool isHor)`	设置横向或纵向。	`isHor`：`true` 为横向。	`void`
`setItemSize(int size)`	设置项主方向尺寸。	`size`：尺寸像素。	`void`
`setItemSpace(int space)`	设置项间距。	`space`：间距像素。	`void`
`setShowText(bool show)`	是否显示文字。	`show`：是否显示文字。	`void`
`setShowIcon(bool show)`	是否显示图标。	`show`：是否显示图标。	`void`
`currentChanged(int index)`	当前项变化信号。	`index`：新索引。	`void`

UIGQMenu 和 UIGQMenuBar

UIGQMenu 和 UIGQMenuBar 适合传统命令组织。

UIGQMenuBar* menuBar = new UIGQMenuBar(parent);
menuBar->setThemeName("MainMenuBar");

UIGQMenu* fileMenu = new UIGQMenu(menuBar);
fileMenu->setTitle("File");
fileMenu->addAction("Open");
menuBar->addMenu(fileMenu);

常用接口：

接口	说明	参数	返回值
`addAction(const QString& text)`	添加命令项。	`text`：命令文本。	`QAction*`
`addMenu(QMenu* menu)`	添加子菜单或顶层菜单。	`menu`：菜单对象。	`QAction*`
`addSeparator()`	添加分隔线。	无	`QAction*`
`setTitle(const QString& title)`	设置菜单标题。	`title`：标题文本。	`void`
`exec(const QPoint& pos)`	弹出菜单。	`pos`：全局坐标。	`QAction*`
`triggered(QAction* action)`	命令触发信号。	`action`：触发项。	`void`
`setThemeName(const QString& themeName)`	设置菜单主题。	`themeName`：主题名。	`void`

UIGQRibbonBar

UIGQRibbonBar 适合命令密度更高的业务软件。Ribbon 内容通常来自配置文件，也可以由代码创建。

UIGQRibbonBar* ribbon = new UIGQRibbonBar(parent);
ribbon->setThemeName("MainRibbon");
ribbon->loadConfigFile("./ribbon.json");

常用接口：

接口	说明	参数	返回值
`loadConfigFile(const QString& filePath)`	加载 Ribbon 配置。	`filePath`：配置文件路径。	`bool`
`setThemeName(const QString& themeName)`	设置 Ribbon 主题。	`themeName`：主题名。	`void`
`addPage(const QString& title)`	添加 Ribbon 页面。	`title`：页面标题。	`UIGQRibbonPage*`
`setCurrentIndex(int index)`	切换当前页面。	`index`：页面索引。	`void`
`currentIndex() const`	获取当前页面索引。	无	`int`
`buttonClicked(const QString& name)`	Ribbon 按钮点击信号。	`name`：按钮名称。	`void`

UIGQScrollBar

UIGQScrollBar 可独立使用，也可绑定到 UIGQContainer、UIGQScrollView、UIGQTableView 等控件。水平滚动条应使用水平构造或主题，垂直滚动条使用垂直主题。

UIGQScrollBar* hBar = new UIGQScrollBar(Qt::Horizontal, parent);
hBar->setThemeName("qtscrollbarh");
hBar->setWidthHeight(12);

UIGQScrollBar* vBar = new UIGQScrollBar(Qt::Vertical, parent);
vBar->setThemeName("qtscrollbar");
vBar->setWidthHeight(12);

常用接口：

接口	说明	参数	返回值
`setOrientation(Qt::Orientation orientation)`	设置方向。	`orientation`：水平或垂直。	`void`
`orientation() const`	获取方向。	无	`Qt::Orientation`
`setRange(int min, int max)`	设置滚动范围。	`min/max`：范围。	`void`
`setValue(int value)`	设置当前值。	`value`：当前滚动值。	`void`
`value() const`	获取当前值。	无	`int`
`setPageStep(int step)`	设置页步长。	`step`：步长。	`void`
`setWidthHeight(int size)`	设置滚动条厚度。	`size`：厚度像素。	`void`
`valueChanged(int value)`	滚动值变化信号。	`value`：新值。	`void`

使用建议

标签只负责“切换”，页面内容放到 UIGQStackContainer 中。
横向滚动条和垂直滚动条主题分开命名，例如 qtscrollbarh 和 qtscrollbar。
Ribbon 适合功能多的桌面软件，不适合简单表单页。
菜单命令应和按钮命令复用同一业务槽函数，避免交互入口行为不一致。

Qt-UI WidgetKit 导航控件

导航控件

导航控件

控件类型

类继承关系

UIGQTabWidget

UIGQMenu 和 UIGQMenuBar

UIGQRibbonBar

UIGQScrollBar

使用建议