快速接入

快速接入

本章说明 WidgetKit 的基础接入流程。

基础流程

1. 将 WidgetKit 控件源码或库文件加入项目。
2. 配置 include 路径和链接库。
3. 在页面中创建控件实例。
4. 设置主题、状态和业务数据。

CMake 示例

target_include_directories(app PRIVATE path/to/widgetkit/include)
target_link_libraries(app PRIVATE Qt6::Widgets QtUiWidgetKit)

使用建议

• 先从示例工程确认控件效果。
• 再按业务模块逐步替换项目中的自定义控件。
• 统一在应用启动处设置主题参数。

使用指南

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 图标章节获取可直接复制的示例。

AI Skills 接入

WidgetKit AI Skills 接入

WidgetKit Skill 是给 AI 助手使用的控件库知识包，包含 UIGQ 控件体系、主题 JSON、容器布局、按钮/图标状态、SVG 颜色、滚动条、序列化和常见排查规则。它适合让 AI 生成或修改 WidgetKit 页面、主题配置和控件代码。

下载

• 下载 WidgetKit Skill
• 下载全部 Qt-UI Skills

目录结构

uigears-widgetkit/
  SKILL.md
  agents/openai.yaml
  references/
    integration.md
    api-reference.md

适合的 AI 任务

• 生成 WidgetKit 初始化代码和资源加载流程。
• 使用 UIGQContainer、UIGQPushButton、UIGQLineEdit 等控件组装页面。
• 编写或检查 theme.json、style.json。
• 将可复用视觉样式迁移到主题配置。
• 排查 SVG 图标、按钮 hover、fade、滚动条方向、布局比例和绝对停靠问题。
• 生成控件 JSON 属性说明和序列化实现建议。

接入步骤

1. 下载并解压 qt-ui-uigears-widgetkit-skill.zip。
2. 将 uigears-widgetkit 放到 AI 工具可读取的 skills 目录。
3. 需求中明确要求 AI 使用 WidgetKit，例如“使用 UIGears WidgetKit 控件实现这个设置页”。
4. 新项目接入时先让 AI 读取 references/integration.md。
5. 修改控件 API、主题 JSON 或布局问题时，让 AI 读取 references/api-reference.md。

示例提示词

使用 uigears-widgetkit skill，帮我用 UIGQContainer 和 UIGQPushButton 实现一个顶部工具栏，样式通过 theme.json/style.json 配置。

使用 uigears-widgetkit skill，检查这个按钮设置 SVG icon 后为什么显示为黑色，并给出修复建议。

生成代码时的约束

• 初始化顺序保持为 UIGQtLib::init()、设置皮肤目录、加载主题目录、创建窗口。
• WidgetKit 页面优先使用 UIGQ* 控件，不随意混入普通 QWidget + QLayout。
• 可复用外观优先落到 theme.json 和 style.json。
• setDrawBackground(false) 这类绘制行为可以保留在 C++。
• 主题切换不应意外改变布局尺寸，除非主题项明确配置了几何字段。

布局与容器控件

布局与容器控件

布局控件负责组织页面结构、尺寸策略、滚动区域和多页面切换。建议先用 UIGQContainer 搭出页面骨架，再根据内容复杂度引入 UIGQScrollView、UIGQStackContainer、UIGQSplitter 等控件。

控件类型

类继承关系

QWidget
  ├─ UIGQContainer + IUIGQWidgetBase
  ├─ UIGQStackContainer + IUIGQWidgetBase
  ├─ QScrollArea
  │   └─ UIGQScrollView + IUIGQWidgetBase
  │       └─ UIGQPropertyList
  ├─ UIGQSplitter + IUIGQWidgetBase
  ├─ UIGQSpacer + IUIGQWidgetBase
  └─ UIGQGroupBox + IUIGQWidgetBase

布局控件以 QWidget 或 Qt 滚动区域为基础，使用 IUIGQWidgetBase 接入主题、布局比例、尺寸策略和基础序列化能力。UIGQPropertyList 继承自 UIGQScrollView，因此也复用滚动区域能力。

UIGQContainer

UIGQContainer 是 WidgetKit 最常用的布局容器，支持横向、纵向、流式布局和绝对停靠。可通过主题名读取当前主题中的背景样式，也可以通过 C++ 直接设置布局参数。

UIGQContainer* card = new UIGQContainer(parent);
card->setObjectName("settingsCard");
card->setThemeName("CardBg");
card->setChildLayout(UIGQContainer::kVertical);
card->setChildSpace(12);
card->setChildPadding(16, 16, 16, 16);
card->addChildWidget(titleLabel);
card->addChildWidget(formArea, 1);

绝对停靠常用于标题栏按钮、用户信息、浮动工具条等不参与主布局计算的控件。

UIGQContainer* profile = new UIGQContainer(parent);
profile->setChildLayout(UIGQContainer::kHorizontal);
profile->setAbsoluteDock(UIG_RIGHT_BOTTOM, UIG_LEFT_TOP, -184, 8);
profile->setAbsoluteDockAutoSize(true);

常用接口：

UIGQStackContainer

UIGQStackContainer 用于在一个固定区域内切换多个页面。页面尺寸会跟随当前容器刷新，适合 dashboard、设置页、工作台页签等场景。

UIGQStackContainer* stack = new UIGQStackContainer(parent);
stack->setThemeName("WorkspaceBg");
stack->addWidget(dashboardPage);
stack->addWidget(settingsPage);
stack->setCurrentIndex(0);

常用接口：

UIGQScrollView

UIGQScrollView 封装滚动区域和自绘滚动条，适合长内容页面。水平滚动条和垂直滚动条应分别设置方向与主题，避免横纵样式混用。

UIGQScrollView* scroll = new UIGQScrollView(parent);
scroll->setThemeName("FormScrollView");
scroll->setScrollbarSize(false, 12); // vertical
scroll->setScrollbarSize(true, 12);  // horizontal
scroll->setVScrollPos(0);

常用接口：

UIGQSplitter

UIGQSplitter 用于把页面拆成可拖动调整的多个区域。

UIGQSpacer

UIGQSpacer 作为布局占位控件使用，常放在水平工具栏中把右侧按钮推到末尾。

UIGQGroupBox

UIGQGroupBox 用于把相关控件组合到一个带标题的区域中。

使用建议

• 页面骨架优先使用 UIGQContainer，保持布局树清晰。
• setThemeName(...) 只负责外观主题，布局尺寸仍建议由布局参数控制。
• 需要浮在右上、右下的区域使用 setAbsoluteDock(...)，内容尺寸不固定时再开启 setAbsoluteDockAutoSize(true)。
• 长内容不要靠父容器裁剪，使用 UIGQScrollView 承载，并分别配置水平、垂直滚动条。

输入控件

输入控件

输入控件负责用户操作、表单录入和参数选择。WidgetKit 的输入控件继承 Qt 原生控件能力，同时增加主题、状态绘制、SVG 图标、布局策略和通用序列化支持。

控件类型

类继承关系

QWidget
  ├─ QPushButton
  │   └─ UIGQPushButton + IUIGQWidgetBase
  │       └─ UIGQRibbonPushButton
  ├─ QCheckBox
  │   └─ UIGQCheckBox + IUIGQWidgetBase
  ├─ QRadioButton
  │   └─ UIGQRadioButton + IUIGQWidgetBase
  ├─ UIGQSwitch + IUIGQWidgetBase
  ├─ QLineEdit
  │   └─ UIGQLineEdit + IUIGQWidgetBase
  ├─ QTextEdit
  │   └─ UIGQTextEdit + IUIGQWidgetBase
  ├─ QComboBox
  │   └─ UIGQComboBox + IUIGQWidgetBase
  ├─ QSpinBox
  │   └─ UIGQSpinBox + IUIGQWidgetBase
  └─ QSlider
      └─ UIGQSlider + IUIGQWidgetBase

输入控件继承 Qt 原生交互能力，例如文本输入、选择状态、数值范围和信号槽；IUIGQWidgetBase 负责接入 WidgetKit 的主题、布局比例、透明度等统一能力。

UIGQPushButton

UIGQPushButton 支持 Normal、Hot、Pressed、Disable 状态背景和文字样式，支持 PNG/SVG 图标和 fade 高亮效果。

UIGQPushButton* importButton = new UIGQPushButton(parent);
importButton->setObjectName("importButton");
importButton->setText("Import");
importButton->setThemeName("PrimaryButton");
importButton->setIcon(":/images/import.svg");
importButton->setFadeEnabled(true);

透明图标按钮建议使用不绘制背景的接口：

helpButton->setDrawBackground(false);
helpButton->setIcon(":/images/help.svg");

常用接口：

UIGQCheckBox 和 UIGQRadioButton

UIGQCheckBox 和 UIGQRadioButton 都支持选中、未选中、禁用和悬停图标，也支持按状态设置文本样式。

UIGQCheckBox* check = new UIGQCheckBox(parent);
check->setText("Remember settings");
check->setThemeName("DefaultCheckBox");
check->setCheckedIcon(":/images/check-on.svg");
check->setUncheckIcon(":/images/check-off.svg");
check->setShowText(true);
check->setShowIcon(true);

常用接口：

UIGQSwitch

UIGQSwitch 更适合状态开关，支持滑块大小、边距、动画速度和左右文本。

UIGQSwitch* sw = new UIGQSwitch(parent);
sw->setLeftText("Off");
sw->setRightText("On");
sw->setSwitchToLeft(false);
sw->setSwitchSpeed(180);

常用接口：

UIGQLineEdit 和 UIGQTextEdit

UIGQLineEdit 支持 placeholder、密码模式、快捷键录入模式和内容边距。

UIGQLineEdit* search = new UIGQLineEdit(parent);
search->setThemeName(UIG_THEME_LINE_EDIT);
search->setPlaceholderText("搜索");
search->setEditMargin(8, 8, 12, 12);
search->setHotkeyMode(false);

UIGQTextEdit 用于多行文本，适合备注、日志和脚本文本。

常用接口：

UIGQComboBox

UIGQComboBox 适合枚举值和过滤条件。

UIGQComboBox* typeBox = new UIGQComboBox(parent);
typeBox->setThemeName("DefaultComboBox");
typeBox->addItem("Basic");
typeBox->addItem("Advanced");
typeBox->setItemHeight(32);

常用接口：

UIGQSpinBox 和 UIGQSlider

UIGQSpinBox 适合精确整数，UIGQSlider 适合连续数值调整。

UIGQSlider* opacity = new UIGQSlider(parent, Qt::Horizontal);
opacity->setThemeName("DefaultSlider");
opacity->setRange(0, 100);
opacity->setValue(60);
opacity->setThumbSize(16, 16);

常用接口：

使用建议

• 业务按钮优先通过 setThemeName(...) 绑定主题，避免在页面代码里硬编码颜色。
• 图标按钮需要透明背景时使用 setDrawBackground(false)。
• 表单输入建议统一设置 UIGQLineEdit 的边距，避免文字贴边。
• 开关类配置用 UIGQSwitch，多选集合用 UIGQCheckBox，互斥选项用 UIGQRadioButton。

展示控件

展示控件

展示控件用于显示文本、图片、SVG、数值和进度状态。它们通常不负责复杂业务交互，但会承担页面的信息密度、状态表达和主题一致性。

控件类型

类继承关系

QWidget
  ├─ QLabel
  │   ├─ UIGQLabel + IUIGQWidgetBase
  │   └─ UIGQLabelEx + IUIGQWidgetBase
  ├─ UIGQImage + IUIGQWidgetBase
  ├─ QGraphicsView
  │   └─ UIGQSvgView + IUIGQWidgetBase
  ├─ QLCDNumber
  │   └─ UIGQLCDNumber + IUIGQWidgetBase
  └─ QProgressBar
      └─ UIGQProgressBar + IUIGQWidgetBase

展示控件保留 Qt 原生显示控件的基础行为，同时通过 IUIGQWidgetBase 接入主题样式、布局比例和透明度。

UIGQLabel 和 UIGQLabelEx

UIGQLabel 适合基础文本显示，UIGQLabelEx 适合需要更复杂绘制或状态表达的文本控件。

UIGQLabel* title = new UIGQLabel(parent);
title->setObjectName("pageTitle");
title->setThemeName("TitleText");
title->setText("仪表盘");
title->setAlignment(Qt::AlignLeft | Qt::AlignVCenter);

常用接口：

UIGQImage

UIGQImage 支持普通图片、GIF、SVG，并可选择使用 SVG 原始颜色或控件指定颜色。

UIGQImage* avatar = new UIGQImage(parent);
avatar->setImagePath(":/images/avatar.png");
avatar->setStretchDraw(true);

UIGQImage* icon = new UIGQImage(parent);
icon->setSvgPath(":/images/user.svg");
icon->setUseSvgColor(true);
icon->setSvgColor(QColor(31, 111, 235));

当 SVG 本身已经包含设计好的多色信息时，保留原始颜色：

icon->setUseSvgColor(false);

常用接口：

UIGQSvgView

UIGQSvgView 更适合较大 SVG 画布、可缩放图形和带滚动条的 SVG 预览。

UIGQSvgView* svgView = new UIGQSvgView(parent);
svgView->loadSvgFile(":/images/process.svg");
svgView->setThemeName("SvgCanvas");

常用接口：

UIGQLCDNumber

UIGQLCDNumber 用于显示数码管效果的数值。

UIGQProgressBar

UIGQProgressBar 支持背景、前景、文本显示和圆形进度。

UIGQProgressBar* progress = new UIGQProgressBar(parent);
progress->setThemeName("DefaultProgress");
progress->setRange(0, 100);
progress->setValue(72);
progress->setShowText(true);
progress->setCircleProgressBar(true);
progress->setCircleAngleRange(90, 360);

常用接口：

使用建议

• 图片类控件只负责显示，不建议把点击逻辑和业务状态全部塞进图片控件。
• 单色 SVG 图标建议启用 setUseSvgColor(true)，由主题或代码统一颜色。
• 多色品牌图、产品图、插图应保留 SVG 原始颜色。
• 进度控件需要同时表达数值和状态时，配合 UIGQLabel 显示辅助说明。

数据控件

数据控件

数据控件用于展示列表、表格、树和属性面板。它们通常需要同时处理数据模型、滚动条、行高、选中状态和单元格样式。

控件类型

类继承关系

QWidget
  ├─ QTableView
  │   └─ UIGQTableView + IUIGQWidgetBase
  ├─ QTreeView
  │   └─ UIGQTreeView + IUIGQWidgetBase
  ├─ QListView
  │   └─ UIGQListView + IUIGQWidgetBase
  ├─ QListWidget
  │   └─ UIGQList + IUIGQWidgetBase
  └─ QScrollArea
      └─ UIGQScrollView + IUIGQWidgetBase
          └─ UIGQPropertyList

数据控件保留 Qt Model/View 或列表控件能力，WidgetKit 扩展表头、滚动条、行项样式、自定义列控件和主题配置。

UIGQTableView

UIGQTableView 基于 QTableView，增加自绘表头、行项样式、复选框列、滚动条样式和自定义列控件。

UIGQTableView* table = new UIGQTableView(parent);
table->setThemeName("DefaultTable");
table->setItemHeight(36);
table->setCheckstyle(true);
table->setScrollbarSize(false, 12);
table->setScrollbarSize(true, 12);
table->setModel(model);

常用接口：

UIGQTreeView

UIGQTreeView 适合目录、分组、配置树和层级数据，支持表头样式、项样式、行高和滚动条主题。

UIGQTreeView* tree = new UIGQTreeView(parent);
tree->setThemeName("DefaultTree");
tree->setItemHeight(30);
tree->setScrollbarSize(false, 12);
tree->setModel(model);

常用接口：

UIGQListView

UIGQListView 适合结果列表、消息列表和卡片式条目。可配置 item 模板、宽高、选中状态和滚动条。

UIGQListView* list = new UIGQListView(parent);
list->setThemeName("DefaultListView");
list->setItemHeight(48);
list->setItemWidth(280);
list->setEnableSelection(true);
list->setModel(model);

常用接口：

UIGQList

UIGQList 是更轻量的列表封装，适合简单项集合。

UIGQPropertyList

UIGQPropertyList 适合属性编辑和对象参数展示，继承滚动区域能力。

使用建议

• 大数据列表保持 Qt Model/View 分层，WidgetKit 负责外观和交互一致性。
• 表格中需要操作按钮时，优先使用自定义列控件，避免把所有操作塞进文本。
• 横向内容较宽时显式配置水平滚动条主题，避免宽列被挤压。
• 属性面板适合低频配置，不建议承载大量实时数据。

导航控件

导航控件

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

控件类型

类继承关系

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);
});

常用接口：

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);

常用接口：

UIGQRibbonBar

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

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

常用接口：

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);

常用接口：

使用建议

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

图形与画布控件

图形与画布控件

图形类控件用于承载自定义绘制、OpenGL 场景和轻量可视化。Chart 类控件已归入 ChartKit 文档，本章节只说明 WidgetKit 中非图表的图形控件。

控件类型

类继承关系

QWidget
  ├─ UIGQCanvas + IUIGQWidgetBase
  └─ QOpenGLWidget
      ├─ UIGQOpenGLWidget + OpenGLFunctions
      └─ UIGQOGLWidget

UIGQCanvas 属于 WidgetKit 主题控件，支持 IUIGQWidgetBase 的主题和布局能力。UIGQOpenGLWidget 与 UIGQOGLWidget 更接近渲染承载控件，继承 Qt OpenGL 体系，重点提供硬件绘制区域。

UIGQCanvas

UIGQCanvas 适合绘制辅助图形、状态标记和轻量的自定义视图。业务可以继承或组合使用它，将绘制逻辑集中在图形层。

UIGQCanvas* canvas = new UIGQCanvas(parent);
canvas->setObjectName("annotationCanvas");
canvas->setThemeName("CanvasBg");
canvas->setDrawBackground(true);

常用接口：

对于交互复杂的画布，建议拆分为数据层、绘制层和操作层，不要在 paintEvent 中直接计算大量业务数据。

UIGQOpenGLWidget 和 UIGQOGLWidget

UIGQOpenGLWidget / UIGQOGLWidget 用于需要硬件渲染的场景，例如 3D 模型、工业设备视图和高频图形刷新区域。

UIGQOGLWidget* view = new UIGQOGLWidget(parent);
view->setObjectName("sceneView");
view->setThemeName("OpenGLPanel");
view->setDrawBackground(false);

常用接口：

使用建议

• Chart 相关控件不要放在 WidgetKit 页面文档中，统一查看 ChartKit 文档。
• 高频绘制区域避免和复杂 QWidget 层级过度嵌套。
• 画布背景、边框和圆角仍建议通过 setThemeName(...) 绑定主题。
• OpenGL 控件的生命周期要和页面切换协调，避免隐藏页面继续高频刷新。

按钮控件

按钮控件

UIGQPushButton 是 WidgetKit 的按钮控件，用于普通操作按钮、主按钮、图标按钮、工具栏按钮和导航按钮。

按钮支持按状态配置背景和文字样式，支持 PNG/SVG 图标，SVG 图标可以保留原始颜色，也可以由控件统一指定颜色。

常见状态

• 默认状态（Normal）
• 鼠标悬停状态（Hot）
• 鼠标按下状态（Pressed）
• 禁用状态（Disable）

C++ 使用

UIGQPushButton* button = new UIGQPushButton(parent);
button->setObjectName("saveButton");
button->setText("保存");
button->setThemeName("PrimaryButton");
button->setIcon(":/UIGearsWidgetKit/images/save.svg");
button->setFadeEnabled(true);
button->setFadeDuration(160);

按钮 fade 效果默认关闭。可以通过全局配置统一开启，也可以单独设置某个按钮：

UIGQtLib::UIGGlobalConfig config;
config.globalFontFamily = "Microsoft YaHei";
config.buttonFadeEnabled = true;
config.buttonFadeDuration = 160;
UIGQtLib::uigSetGlobalConfig(config);

button->setFadeEnabled(false);

类继承关系

QWidget
  └─ QAbstractButton
      └─ QPushButton
          └─ UIGQPushButton

IUIGQWidgetBase
  └─ UIGQPushButton

UIGQPushButton 同时继承 Qt 的 QPushButton 和 WidgetKit 的 IUIGQWidgetBase。因此它既可以使用 Qt 标准按钮能力，例如 setText(...)、clicked 信号、setEnabled(...)，也可以使用 WidgetKit 的主题、布局和 JSON 序列化能力。

内部实现上，每个 UIGQPushButton 持有一个 UIGQWidgetBase 基础控制对象和一个 UIGQPushButtonImpl 绘制实现对象：

控件接口说明

构造

主题和序列化

背景和状态样式

Fade 动画

图标

文本

WidgetKit 通用布局接口

信号

主题样式建议

按钮背景、文字、图标颜色建议放到主题中维护。业务代码只负责设置文本、图标路径、状态和动作，避免把颜色、圆角、边框写散在页面逻辑里。

使用建议

• 普通业务按钮优先通过 setThemeName(...) 绑定主题，不建议在页面代码里硬编码颜色。
• 图标按钮如果不需要背景，使用 drawBackground: false 或 setDrawBackground(false)。
• SVG 图标需要统一适配主题色时，设置 iconUseColor: true 和 iconColor。
• 页面中主按钮数量应保持克制，避免多个强强调按钮同时出现。

输入框控件

输入框控件

UIGQLineEdit 是 WidgetKit 的单行文本输入控件，用于搜索框、表单输入、密码输入、快捷键输入和参数编辑。

输入框控件支持按状态配置背景和文字样式，支持 placeholder 文本样式，支持密码模式和快捷键录入模式。

常见状态

• 默认状态（Normal）
• 鼠标悬停状态（Hot）
• 获得焦点状态（Pressed）
• 禁用状态（Disable）

C++ 使用

UIGQLineEdit* edit = new UIGQLineEdit(parent);
edit->setObjectName("searchEdit");
edit->setThemeName(UIG_THEME_LINE_EDIT);
edit->setText("");
edit->setPlaceholderText("搜索");
edit->setEditMargin(8, 8, 12, 12);

密码输入：

edit->setIsPassword(true);

快捷键输入：

edit->setHotkeyMode(true);

快捷键模式下，用户按下 Ctrl、Alt、Shift 与字母组合时，控件会把组合键写入文本；按 Delete 或 Backspace 会清空文本。

类继承关系

QWidget
  └─ QLineEdit
      └─ UIGQLineEdit

IUIGQWidgetBase
  └─ UIGQLineEdit

UIGQLineEdit 同时继承 Qt 的 QLineEdit 和 WidgetKit 的 IUIGQWidgetBase。因此它既可以使用 Qt 标准输入框能力，例如 setText(...)、textChanged 信号、setEchoMode(...)，也可以使用 WidgetKit 的主题、布局和 JSON 序列化能力。

内部实现上，每个 UIGQLineEdit 持有一个 UIGQWidgetBase 基础控制对象和一个 UIGQLineEditImpl 绘制实现对象：

控件接口说明

构造

主题和序列化

背景和状态样式

文本和输入模式

WidgetKit 通用布局接口

常用信号

主题样式建议

输入框背景、边框、文字、placeholder 样式建议放到主题中维护。业务代码只负责设置文本、placeholder、密码模式、快捷键模式和边距。

使用建议

• 表单输入框优先通过 setThemeName(UIG_THEME_LINE_EDIT) 绑定主题，不建议在页面代码里硬编码颜色。
• 搜索框可以配合左侧搜索图标容器使用，输入框本身负责输入和 placeholder。
• 密码模式会禁止复制、粘贴、全选等快捷操作，适合敏感输入。
• 快捷键模式适合设置页中的热键录入，不适合作为普通文本输入框使用。

复选框控件

复选框控件

复选框控件用于多选、配置项、权限项和开关型参数。

常见状态

• 未选中（Unchecked）
• 已选中（Checked）
• 半选（Indeterminate）
• 禁用（Disabled）
• 错误提示（Error）

风格参数

类继承关系

QWidget
  └─ QCheckBox
      └─ UIGQCheckBox + IUIGQWidgetBase

UIGQCheckBox 继承 Qt 的 QCheckBox，保留选中、半选、禁用和信号槽能力；同时通过 IUIGQWidgetBase 接入 WidgetKit 主题、图标状态、布局比例和 JSON 序列化。

常用方法

适用建议

批量选择场景建议配合表格表头的半选状态使用。

SVG 图标

UIGQCheckBox 和 UIGQRadioButton 支持为选中、未选中等状态直接配置 SVG 路径。

SVG 图标

WidgetKit SVG 图标

WidgetKit 已支持在统一的字符串图标渲染路径中直接使用 .svg 路径。下面这些控件可以直接配置 SVG 文件，不需要额外封装为 QIcon。

支持的控件

• UIGQPushButton
• UIGQRibbonPushButton
• UIGQCheckBox
• UIGQRadioButton
• UIGQComboBox 下拉按钮图标
• UIGQTabWidget 标签页图标
• UIGQScrollBar 箭头和滑块图标

支持的路径形式

• Qt 资源路径：:/UIGearsWidgetKit/images/home.svg
• 皮肤或主题相对路径：images/home.svg
• 文件系统路径：./icons/home.svg

C++ 示例

UIGQPushButton* button = new UIGQPushButton(parent);
button->setThemeName(UIG_THEME_ICON_WITH_TEXT_BUTTON);
button->setIcon(":/UIGearsWidgetKit/images/home.svg");

UIGQComboBox* combo = new UIGQComboBox(parent);
combo->setThemeName(UIG_THEME_TEXT_COMBOBOX);
combo->setNormalBtnIcon(":/UIGearsWidgetKit/images/chevron-down.svg");
combo->setHotBtnIcon(":/UIGearsWidgetKit/images/chevron-down.svg");

UIGQScrollBar* scrollBar = new UIGQScrollBar(parent);
scrollBar->setOrientation(Qt::Vertical);
scrollBar->setScrollbarBtnIcon(true, ":/UIGearsWidgetKit/images/chevron-up.svg");
scrollBar->setScrollbarBtnIcon(false, ":/UIGearsWidgetKit/images/chevron-down.svg");
scrollBar->setScrollbarThumbIcon(":/UIGearsWidgetKit/images/grip.svg");

主题 JSON 示例

{
  "attr": {
    "btnIcon": ":/UIGearsWidgetKit/images/chevron-down.svg",
    "btnHotIcon": ":/UIGearsWidgetKit/images/chevron-down.svg"
  }
}

使用建议

• 建议使用稳定的 viewBox 尺寸，例如 16x16、18x18 或 20x20。
• 禁用状态不需要单独准备灰色 SVG，库会自动绘制禁用态效果。
• 文本和图标组合使用的控件，建议在示例程序中检查一次实际间距，确保当前主题下的显示效果合适。

仪表盘控件

仪表盘控件

仪表盘控件用于展示实时数值、设备指标、阈值区间和风险状态。

常见能力

• 数值和单位显示。
• 最小值、最大值和当前值。
• 阈值色带。
• 警告和危险状态。

风格参数

适用建议

仪表盘适合关键指标展示，不建议在同一页面放置过多大尺寸仪表盘。

授权说明

授权说明

WidgetKit 提供试用版、基础版和完整版。

试用版

用于评估、学习和原型验证，不提供源码，不支持商用。

基础版

包含 WidgetKit 单产品完整源码，支持单项目商用，包含 1 年版本免费升级权益，提供邮件 + 工单支持。

完整版

统一价格为 ￥12,800，包含 StyleKit、WidgetKit、ChartKit、AgentKit 全系列 4 款产品完整源码，不限商用项目数量，包含 1 年版本免费升级权益，提供邮件 + 工单 + 优先支持。

说明

实际授权范围以购买时的订单和协议为准。