使用指南

WidgetKit 使用指南

本章参考 UIGearsWidgetKit 示例程序，说明如何初始化控件库、加载皮肤和主题、创建 Ribbon 导航，并在页面中使用 UIGQ* 自定义控件。

运行示例程序

WidgetKit 示例工程位于仓库根目录的 UIGearsWidgetKit，构建目标名称为 UIGearsWidgetKit。

cmake --build build_msvc_debug --config Debug --target UIGearsWidgetKit --parallel
build_msvc_debug/bin/Debug/UIGearsWidgetKit.exe

构建后会复制运行所需资源：

ThemeShow：皮肤工程目录。
theme1、theme2、theme3：主题目录。
ribbon.json：顶部 Ribbon 的页面、分组和按钮配置。

初始化流程

示例程序在 main.cpp 中使用目录加载方式初始化运行环境：

QApplication a(argc, argv);

UIGQtLib::init();
UIGQtLib::uigSetSkinFilePath("./ThemeShow");
UIGQtLib::uigLoadThemeDir("./theme3");

UIGearsWidgetKit w;
w.show();

int ret = a.exec();
UIGQtLib::shutdown();
return ret;

实际项目中建议保持同样顺序：先初始化库，再设置皮肤目录，再加载主题目录，最后创建窗口。

创建页面

示例窗口继承 UIGQWindow，先通过皮肤文件创建基础窗口，再在内容容器里创建控件页面。

UIGQtLib::uigCreatePageByFileName(this, "main");

_container = findChild<UIGQContainer*>("container");
_close = findChild<UIGQPushButton*>("close");
_min = findChild<UIGQPushButton*>("min");

关键控件建议做空指针检查。皮肤文件缺失或对象名变化时，应给出错误提示，而不是继续访问空指针。

设置主题名

WidgetKit 控件通过 setThemeName(...) 绑定主题项。示例中常见写法如下：

UIGQPushButton* button = new UIGQPushButton(parent);
button->setThemeName(UIG_THEME_TEXT_BUTTON);

UIGQComboBox* combo = new UIGQComboBox(parent);
combo->setThemeName(UIG_THEME_TEXT_COMBOBOX);

UIGQScrollBar* scrollBar = new UIGQScrollBar(parent);
scrollBar->setThemeName(UIG_THEME_SCROLLBAR_VERTICAL);

主题切换后，资源管理器会刷新已注册控件。业务代码只需要保持控件使用统一的主题名。

Ribbon 导航

示例中顶部导航使用 UIGQRibbonBar，配置来自 ribbon.json：

_navigationRibbon = new UIGQRibbonBar(this);
_navigationRibbon->setThemeName(UIGQRibbonBar::typeName());
_navigationRibbon->setGeometry(0, 50, 950, 130);
_navigationRibbon->loadConfigFile("./ribbon.json");

ribbon.json 支持页签、分组和内容项：

{
  "topBarHeight": 34,
  "tabHeight": 30,
  "groupHeight": 76,
  "groupRowCount": 3,
  "tabs": [
    {
      "name": "home",
      "displayName": "开始",
      "groups": [
        {
          "name": "clipboard",
          "displayName": "剪贴板",
          "content": [
            { "itemType": "largeButton", "name": "navButton", "text": "按钮" },
            { "itemType": "smallButton", "name": "navCheck", "text": "复选" }
          ]
        }
      ]
    }
  ]
}

常用 itemType 包括：

largeButton
smallButton
menuButton
comboBox
progressBar
checkBox
radioButton
label
lineEdit
spinBox
switch
separator

Ribbon 按钮可以通过对象名查找并连接业务页面：

UIGQPushButton* button = _navigationRibbon->findChild<UIGQPushButton*>("navButton");
connect(button, &QPushButton::clicked, this, [this]() {
    showPage(_buttonShowWin);
});

页面切换

示例里每个控件类别都是一个 UIGQContainer 页面，点击 Ribbon 按钮时只显示目标页面：

void showPage(UIGQContainer* page)
{
    const QObjectList& list = _container->children();
    for (QObject* object : list) {
        QWidget* widget = qobject_cast<QWidget*>(object);
        if (widget) {
            widget->setVisible(widget == page);
        }
    }
}

这种方式适合控件展示、设置页、工具页等页面数量固定的场景。业务系统也可以替换为 QStackedWidget 或自己的页面管理器。

主题切换

示例提供主题切换弹窗，切换时直接加载不同主题目录：

bool loadThemeDir(const QString& themeDir)
{
    QByteArray themePath = themeDir.toLocal8Bit();
    return UIGQtLib::uigLoadThemeDir(themePath.constData());
}

运行目录下保留 theme1、theme2、theme3 后，就可以在运行时切换风格。新增主题时，建议复制一套已有主题目录，再调整 theme.json、style.json 和图片资源。

接入建议

先运行 UIGearsWidgetKit demo，确认皮肤、主题和 Ribbon 配置能正常加载。
页面内优先使用 UIGQContainer、UIGQPushButton、UIGQComboBox、UIGQCheckBox、UIGQRadioButton、UIGQTableView 等内部控件。
对 findChild 的关键结果做空指针保护。
资源目录使用相对运行目录的路径，便于发布和调试。
自定义 Ribbon 内容优先改 ribbon.json，只有新增控件类型或交互模型时再扩展 UIGQRibbonBar。

SVG 图标

UIGearsWidgetKit 示例已经演示了 SVG 在按钮、复选框/单选框图标、ComboBox 下拉按钮、标签页图标、滚动条箭头与滑块、表格单元格图标以及 Ribbon 快捷操作中的用法。可查看专门的 SVG 图标章节获取可直接复制的示例。

Qt-UI WidgetKit 使用指南