中文 EN
文档

Qt-UI WidgetKit 文档

Qt 自定义控件集合，实现功能更加强大的用户界面。

返回产品页 查看 StyleKit 文档 查看 ChartKit 文档

产品概览

Qt-UI WidgetKit 产品概览

WidgetKit 是面向 Qt Widgets 项目的自定义控件库，聚焦工业软件、业务系统、设备控制台和数据面板中的高频控件。

适用场景

  • 数据看板与实时监控。
  • 设备参数配置与状态展示。
  • 内部业务系统的产品化界面。
  • 需要统一交互和视觉规范的 Qt 项目。

核心内容

  • 按钮、复选框等基础控件增强。
  • 仪表盘、状态卡片、图表容器等业务控件。
  • 统一主题、尺寸、状态和参数接口。
  • 示例工程和接入说明。

基类和类图

WidgetKit 控件通常在 Qt 原生控件基础上扩展绘制、主题、布局比例和 JSON 序列化能力。大多数控件同时实现 IUIGQWidgetBase，内部再持有 UIGQWidgetBase 通用数据对象和对应的 *Impl 绘制/逻辑实现对象。

QObject
  └─ QWidget
      ├─ QPushButton
      │   └─ UIGQPushButton + IUIGQWidgetBase
      │       └─ UIGQRibbonPushButton
      ├─ QCheckBox
      │   └─ UIGQCheckBox + IUIGQWidgetBase
      ├─ QRadioButton
      │   └─ UIGQRadioButton + IUIGQWidgetBase
      ├─ QLineEdit
      │   └─ UIGQLineEdit + IUIGQWidgetBase
      ├─ QTextEdit
      │   └─ UIGQTextEdit + IUIGQWidgetBase
      ├─ QComboBox
      │   └─ UIGQComboBox + IUIGQWidgetBase
      ├─ QTableView
      │   └─ UIGQTableView + IUIGQWidgetBase
      ├─ QTreeView
      │   └─ UIGQTreeView + IUIGQWidgetBase
      ├─ QScrollArea
      │   └─ UIGQScrollView + IUIGQWidgetBase
      │       └─ UIGQPropertyList
      ├─ QLabel
      │   ├─ UIGQLabel + IUIGQWidgetBase
      │   └─ UIGQLabelEx + IUIGQWidgetBase
      ├─ QOpenGLWidget
      │   ├─ UIGQOpenGLWidget
      │   └─ UIGQOGLWidget
      ├─ UIGQContainer + IUIGQWidgetBase
      ├─ UIGQStackContainer + IUIGQWidgetBase
      ├─ UIGQTabWidget + IUIGQWidgetBase
      ├─ UIGQRibbonBar + IUIGQWidgetBase
      ├─ UIGQImage + IUIGQWidgetBase
      ├─ UIGQCanvas + IUIGQWidgetBase
      └─ UIGQSwitch + IUIGQWidgetBase

IUIGQWidgetBase 提供统一的主题、布局比例、透明度、JSON 读写和类型名接口；UIGQWidgetBase 保存这些通用状态；具体控件的 *Impl 类负责状态绘制、主题解析和控件专属属性。

快速接入

快速接入

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

布局与容器控件

布局与容器控件

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

控件类型

控件 JSON type 典型用途
UIGQContainer qtcontainer 横向、纵向、流式、绝对停靠布局，页面背景与卡片容器
UIGQStackContainer qtstackcontainer 多页面区域、向导、工作区视图切换
UIGQScrollView qtscrollview 长表单、列表面板、可滚动内容区
UIGQSplitter qtsplitter 左右面板、上下分区、可调整工作区
UIGQSpacer qtspacer 弹性间距、占位、推开控件
UIGQGroupBox qtgroupbox 分组设置区、表单分组、视觉归类

类继承关系

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

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

UIGQContainer

UIGQContainer 是 WidgetKit 最常用的布局容器，支持横向、纵向、流式布局和绝对停靠。可通过主题名读取 theme.json 中的背景样式，也可以通过 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);

常用接口：

接口 说明 参数 返回值
addWidget(QWidget*) 添加页面。 widget：要添加的页面控件。 int，新增页面索引
insertWidget(int, QWidget*) 插入页面。 index：插入位置；widget：页面控件。 int，实际插入索引
removeWidget(QWidget*) 移除页面。 widget：要移除的页面控件。 void
setCurrentIndex(int) 切换当前页。 index：目标页面索引。 void
currentWidget() 获取当前页控件。 无 QWidget*

UIGQScrollView

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

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

滚动条相关样式可直接在主题中配置，也可以通过接口设置：

接口 说明 参数 返回值
setScrollbarSize(bool isHorizontal, int size) 设置滚动条厚度。 isHorizontal：是否水平滚动条；size：厚度。 void
setScrollbarBtnSize(bool isHorizontal, int size) 设置滚动条按钮大小。 isHorizontal：是否水平滚动条；size：按钮尺寸。 void
setScrollbarBackgroundStyle(bool isHorizontal, const FillStyle& background) 设置轨道背景。 isHorizontal：是否水平滚动条；background：轨道背景样式。 void
setScrollbarThumbStyle(bool isHorizontal, CtrlState state, const FillStyle& style) 设置滑块状态样式。 isHorizontal：是否水平滚动条；state：滑块状态；style：滑块样式。 void
setScrollbarButtonIcon(bool isHorizontal, bool isUpOrLeft, const QString& iconPath) 设置方向按钮图标。 isHorizontal：是否水平滚动条；isUpOrLeft：是否上/左按钮；iconPath：图标路径。 void

JSON 示例

{
  "type": "qtcontainer",
  "name": "contentCard",
  "theme": "CardBg",
  "x": 24,
  "y": 24,
  "w": 420,
  "h": 240,
  "attr": {
    "childLayout": 1,
    "childSpace": 12,
    "paddingLeft": 16,
    "paddingTop": 16,
    "paddingRight": 16,
    "paddingBottom": 16,
    "drawBackground": true,
    "absoluteDockAutoSize": false
  }
}

使用建议

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

输入控件

输入控件

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

控件类型

控件 JSON type 典型用途
UIGQPushButton qtbutton 操作按钮、图标按钮、工具按钮
UIGQCheckBox qtcheckbox 多选项、批量选择、布尔配置
UIGQRadioButton qtradiobox 互斥选项、模式切换、分组选择
UIGQSwitch qtswitch 开关状态、启停选项、轻量布尔配置
UIGQLineEdit qtdedit 单行文本、搜索、密码、快捷键录入
UIGQTextEdit qttext 多行备注、说明、脚本或日志编辑
UIGQComboBox qtcombobox 下拉枚举、筛选条件、参数选择
UIGQSpinBox qtspinbox 整数输入、步进调整
UIGQSlider qtslider 连续数值、比例、阈值调整

类继承关系

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 的主题、布局比例、JSON 和透明度等统一能力。

按钮

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

透明图标按钮建议使用不绘制背景的接口，而不是设置透明 FillStyle：

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

选择类控件

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* sw = new UIGQSwitch(parent);
sw->setLeftText("Off");
sw->setRightText("On");
sw->setSwitchToLeft(false);
sw->setSwitchSpeed(180);

文本输入

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

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

快捷键录入：

shortcutEdit->setHotkeyMode(true);

密码输入：

passwordEdit->setIsPassword(true);

选择与数值控件

UIGQComboBox 适合枚举值和过滤条件；UIGQSpinBox 适合精确整数；UIGQSlider 适合连续数值调整。

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

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

JSON 示例

{
  "type": "qtbutton",
  "name": "saveButton",
  "theme": "PrimaryButton",
  "x": 16,
  "y": 16,
  "w": 120,
  "h": 36,
  "attr": {
    "text": "保存",
    "hasIcon": true,
    "iconPath": ":/images/save.svg",
    "showText": true,
    "drawBackground": true,
    "fadeEnabled": true,
    "fadeDuration": 160
  }
}

使用建议

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

展示控件

展示控件

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

控件类型

控件 JSON type 典型用途
UIGQLabel qtlabel 标题、字段名、说明文字
UIGQLabelEx qtlabelex 扩展文本、强调信息、复杂状态文本
UIGQImage qtpicture 位图、头像、插图、SVG 图标显示
UIGQSvgView qtsvgview 可缩放 SVG 画布和矢量预览
UIGQLCDNumber qtlcdnumber 数码管、仪表读数
UIGQProgressBar qtprogressbar 线性或圆形进度

类继承关系

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

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

文本显示

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

UIGQLabel* title = new UIGQLabel(parent);
title->setObjectName("pageTitle");
title->setThemeName("TitleText");
title->setText("仪表盘");

文本样式建议放到 style.json 中，然后在 theme.json 的控件主题里引用，页面代码只保留业务文本。

图片与 SVG

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 更适合较大 SVG 画布、可缩放图形和带滚动条的 SVG 预览。

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

进度控件

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

JSON 示例

{
  "type": "qtpicture",
  "name": "statusIcon",
  "theme": "ToolbarIcon",
  "x": 12,
  "y": 12,
  "w": 24,
  "h": 24,
  "attr": {
    "svgPath": ":/images/check.svg",
    "useSvgColor": true,
    "svgColor": "FF21A2A8",
    "stretch": true
  }
}

使用建议

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

数据控件

数据控件

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

控件类型

控件 JSON type 典型用途
UIGQTableView qtdatagrid 表格、业务列表、明细矩阵
UIGQTreeView qttree 层级结构、目录树、组织关系
UIGQListView qtlistview 列表视图、模板项、结果集合
UIGQList qtlist 简单列表封装
UIGQPropertyList qtproperty 属性表、参数面板、对象配置

类继承关系

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

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

表格

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

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

常用接口：

接口 说明 参数 返回值
setItemHeight(int) 设置行高。 height：行高，单位像素。 void
setCheckstyle(bool) 开启表格复选框样式。 enabled：是否启用复选框样式。 void
setColumnWidget(int, UIGQContainer*) 为列配置自定义控件。 column：列索引；widget：自定义控件容器。 void
selectedRows() 获取当前选择行。 无 QList<int>
headerCheckedChanged(bool) 表头复选框变化信号。 checked：表头是否选中。 void
customControlClicked(int, QString) 自定义单元格控件点击信号。 row：行索引；name：控件名称。 void

树控件

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

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

树控件仍使用 Qt 的 Model/View 数据方式，主题只负责外观绘制。

列表视图

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

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

当条目需要复杂内容时，可通过 setItemTemplate(...) 配置模板控件，并结合回调更新模板内容。

JSON 示例

{
  "type": "qtdatagrid",
  "name": "policyTable",
  "theme": "DefaultTable",
  "x": 24,
  "y": 80,
  "w": 920,
  "h": 420,
  "attr": {
    "itemHeight": 36,
    "checkstyle": true,
    "vScrollSize": 12,
    "hScrollSize": 12
  }
}

使用建议

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

导航控件

导航控件

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

控件类型

控件 JSON type 典型用途
UIGQTabWidget qttab 顶部/侧边标签、模块切换
UIGQMenu qtmenu 上下文菜单、命令菜单
UIGQMenuBar qtmenubar 窗口级菜单栏
UIGQRibbonBar qtribbonbar Ribbon 命令区、复杂工具栏
UIGQScrollBar qtscrollbar 独立滚动条、容器绑定滚动

类继承关系

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* 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(text, icon, selectedIcon) 添加标签项。 text：标签文字；icon：普通图标；selectedIcon：选中图标。 void
setSelectedIndex(int) 设置当前选中项。 index：目标标签索引。 void
setIsHor(bool) 设置横向或纵向。 isHor：true 为横向，false 为纵向。 void
setShowText(bool) 是否显示文字。 show：是否显示文字。 void
setShowIcon(bool) 是否显示图标。 show：是否显示图标。 void

菜单与 Ribbon

UIGQMenu 和 UIGQMenuBar 适合传统命令组织，UIGQRibbonBar 适合命令密度更高的业务软件。

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

UIGQRibbonBar* ribbon = new UIGQRibbonBar(parent);
ribbon->setThemeName("MainRibbon");

菜单类控件建议保持命令层级清晰，常用命令放工具栏或按钮，低频命令放菜单。

滚动条

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

JSON 示例

{
  "type": "qttab",
  "name": "mainTabs",
  "theme": "DefaultTabs",
  "x": 16,
  "y": 16,
  "w": 360,
  "h": 40,
  "attr": {
    "isHor": true,
    "itemSize": 96,
    "itemSpace": 8,
    "showText": true,
    "showIcon": true
  }
}

使用建议

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

图形与画布控件

图形与画布控件

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

控件类型

控件 JSON type 典型用途
UIGQCanvas canvas 自定义绘制、标注层、轻量图形区域
UIGQOpenGLWidget 由控件实现定义 3D 场景、硬件加速绘制
UIGQOGLWidget qtoglwidget OpenGL 场景封装、兼容渲染区域

类继承关系

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

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

Canvas

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

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

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

OpenGL 控件

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

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

OpenGL 区域通常建议放在独立容器里，并通过 setDrawBackground(false) 或透明容器减少重复绘制。

JSON 示例

{
  "type": "canvas",
  "name": "annotationCanvas",
  "theme": "CanvasBg",
  "x": 24,
  "y": 24,
  "w": 640,
  "h": 360
}

使用建议

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

按钮控件

按钮控件

UIGQPushButton 是 WidgetKit 的按钮控件，JSON 类型名为 qtbutton。它用于普通操作按钮、主按钮、图标按钮、工具栏按钮和导航按钮。

按钮支持按状态配置背景和文字样式，支持 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 绘制实现对象：

类型 作用
QPushButton Qt 标准按钮基类，提供点击、文本、启用禁用、事件分发等基础能力。
IUIGQWidgetBase WidgetKit 控件统一接口，提供主题名、布局策略、JSON 读写等能力。
UIGQWidgetBase 控件通用数据对象，保存布局、主题、透明度等基础属性。
UIGQPushButtonImpl 按钮专用实现，负责背景、文字、图标、fade 动画和 JSON 属性读写。

控件接口说明

构造和类型

接口 说明 参数 返回值
UIGQPushButton(QWidget* parent = nullptr) 创建按钮控件。 parent：父控件，可为空。 控件实例
static const char* typeName() 返回 JSON 类型名，按钮为 qtbutton。 无 const char*
QString getTypeName() const 返回当前控件类型名。来自 WidgetKit 基础接口。 无 QString

主题和 JSON

接口 说明 参数 返回值
void setThemeName(const QString& themeName) 设置主题名。控件会从当前主题的 theme.json 中读取同名配置。 themeName：主题配置名称。 void
QString getThemeName() const 获取当前主题名。 无 QString
bool readJsonValue(void* value) 从 Json::Value 读取控件配置。通常由页面加载或设计器调用。 value：指向 Json::Value 的配置对象。 bool，读取是否成功
bool serializeJsonValue(Json::Value* value, bool bRead = true) bRead=true 时读取 JSON，bRead=false 时写出 JSON。 value：JSON 对象；bRead：是否读取。 bool，序列化是否成功
QString jsonData() const 获取设计器属性中的 JSON 字符串。 无 QString
void setJsonData(const QString& data) 设置设计器属性中的 JSON 字符串，并在首次设置时读取配置。 data：JSON 字符串。 void

背景和状态样式

接口 说明 参数 返回值
void setUseFillStyle(CtrlState state, bool useFillStyle) 指定某个状态是否使用颜色填充样式。state 可传 UIG_STATE_ALL 批量设置。 state：控件状态；useFillStyle：是否使用填充样式。 void
bool getUseFillStyle(CtrlState state) 获取某个状态是否使用颜色填充样式。 state：控件状态。 bool
void setDrawBackground(bool drawBackground) 设置是否绘制按钮背景。图标按钮、透明按钮常设为 false。 drawBackground：是否绘制背景。 void
bool getDrawBackground() const 获取是否绘制背景。 无 bool
void setBackground(CtrlState state, const FillStyle& fillStyle) 设置某个状态的背景样式。state 可传 UIG_NORMAL、UIG_HOT、UIG_PRESSED、UIG_DISABLE 或 UIG_STATE_ALL。 state：控件状态；fillStyle：背景填充样式。 void
const FillStyle& getBackground(CtrlState state) 获取某个状态的背景样式。 state：控件状态。 const FillStyle&
void setTextStyle(CtrlState state, const TextStyleDesc& desc) 设置某个状态的文字样式。 state：控件状态；desc：文字样式描述。 void
const TextStyleDesc& getTextStyle(CtrlState state) 获取某个状态的文字样式。 state：控件状态。 const TextStyleDesc&

Fade 动画

接口 说明 参数 返回值
void setFadeEnabled(bool enabled) 设置当前按钮是否启用 Hot/Normal 状态渐变。 enabled：是否启用渐变。 void
bool getFadeEnabled() const 获取当前按钮是否启用渐变。 无 bool
void setFadeDuration(int duration) 设置渐变时长，单位毫秒。小于等于 0 时按 150 处理。 duration：渐变时长，单位毫秒。 void
int getFadeDuration() const 获取当前渐变时长。 无 int

图标

接口 说明 参数 返回值
void setIcon(const QString& iconPath) 设置图标路径。支持 PNG/SVG 和 Qt 资源路径。 iconPath：图标路径或 Qt 资源路径。 void
const QString getIcon() 获取普通图标路径。 无 QString
void setIcon(const QIcon& icon) 设置 Qt QIcon 图标。 icon：Qt 图标对象。 void
void setHotIcon(const QString& iconPath) 设置 Hot 状态图标路径。 iconPath：Hot 状态图标路径。 void
const QString getHotIcon() 获取 Hot 状态图标路径。 无 QString
void setPressedIcon(const QString& iconPath) 设置 Pressed 状态图标路径。 iconPath：Pressed 状态图标路径。 void
const QString getPressedIcon() 获取 Pressed 状态图标路径。 无 QString
void setUseIcon(bool use) 设置是否绘制图标。 use：是否绘制图标。 void
bool getUseIcon() 获取是否绘制图标。 无 bool
const IconStyleDesc& getIconStyle() 获取图标绘制样式，包括停靠、偏移、SVG 颜色等。 无 const IconStyleDesc&
void setIconStyle(const IconStyleDesc& style) 设置图标绘制样式。 style：图标绘制样式。 void

文本

接口 说明 参数 返回值
void setShowText(bool show) 设置是否绘制按钮文本。 show：是否绘制文本。 void
bool getShowText() 获取是否绘制按钮文本。 无 bool
void setTextOffsetX(int offsetX) 设置文本 X 偏移。 offsetX：X 方向偏移量。 void
int getTextOffsetX() 获取文本 X 偏移。 无 int
void setTextOffsetY(int offsetY) 设置文本 Y 偏移。 offsetY：Y 方向偏移量。 void
int getTextOffsetY() 获取文本 Y 偏移。 无 int

WidgetKit 通用布局接口

接口 说明 参数 返回值
void setLayoutRatio(int ratio) 设置布局比例值。用于比例布局。 ratio：空间占比权重。 void
int getLayoutRatio() const 获取布局比例值。 无 int
void setWidthPolicy(LayoutSizePolicy policy) 设置宽度策略。常用值为 UIG_SIZE_AUTO、UIG_SIZE_FILL、UIG_SIZE_FIXED。 policy：宽度策略枚举。 void
LayoutSizePolicy getWidthPolicy() const 获取宽度策略。 无 LayoutSizePolicy
void setHeightPolicy(LayoutSizePolicy policy) 设置高度策略。 policy：高度策略枚举。 void
LayoutSizePolicy getHeightPolicy() const 获取高度策略。 无 LayoutSizePolicy
void setAbsoluteLayout(bool absoluteLayout) 设置是否使用绝对布局。 absoluteLayout：是否启用绝对布局。 void
bool getAbsoluteLayout() const 获取是否使用绝对布局。 无 bool
void setAbsoluteDock(DockLayoutType hor, DockLayoutType ver, int offsetX = 0, int offsetY = 0) 设置绝对停靠位置和偏移。 hor：水平停靠；ver：垂直停靠；offsetX/offsetY：偏移量。 void
void getAbsoluteDock(DockLayoutType& hor, DockLayoutType& ver, int& offsetX, int& offsetY) const 获取绝对停靠位置和偏移。 hor/ver/offsetX/offsetY：输出停靠与偏移。 void
void setOpacity(int alpha) 设置控件透明度，范围 0-255。 alpha：透明度值。 void
int getOpacity() const 获取控件透明度。 无 int
void resizeWidget() 根据 WidgetKit 布局数据重新计算控件尺寸和位置。 无 void

信号

信号 说明 参数 返回值
void enterSignal() 鼠标进入按钮区域时触发。 无 void
void leaveSignal() 鼠标离开按钮区域时触发。 无 void
void clicked(bool checked = false) Qt QPushButton 标准点击信号。 checked：按钮选中状态。 void

JSON 示例

{
  "type": "qtbutton",
  "name": "saveButton",
  "x": 24,
  "y": 16,
  "w": 120,
  "h": 36,
  "theme": "PrimaryButton",
  "tooltip": "保存当前配置",
  "attr": {
    "text": "保存",
    "hasIcon": true,
    "iconPath": ":/UIGearsWidgetKit/images/save.svg",
    "hotIconPath": ":/UIGearsWidgetKit/images/save-hover.svg",
    "showText": true,
    "drawBackground": true,
    "fadeEnabled": true,
    "fadeDuration": 160,
    "iconUseColor": true,
    "iconColor": "FFFFFFFF",
    "iconHor": 0,
    "iconVer": 1,
    "iconX": 10,
    "iconY": 0,
    "txtX": 28,
    "txtY": 0
  },
  "style": [
    [ "PrimaryButtonBg", 1, 0 ],
    [ "PrimaryButtonHotBg", 1, 1 ],
    [ "PrimaryButtonPressedBg", 1, 2 ],
    [ "PrimaryButtonDisabledBg", 1, 3 ],
    [ "PrimaryButtonText", 2, 4 ],
    [ "PrimaryButtonHotText", 2, 5 ],
    [ "PrimaryButtonPressedText", 2, 6 ],
    [ "PrimaryButtonDisabledText", 2, 7 ]
  ]
}

基础 JSON 属性

字段 类型 默认值 说明
type string 必填 控件类型，按钮固定为 qtbutton。
name string 空 Qt objectName，用于查找控件、调试和局部样式定位。
x int 0 矩形布局下的左上角 X 坐标。
y int 0 矩形布局下的左上角 Y 坐标。
w int 0 控件宽度。
h int 0 控件高度。
theme string 空 主题名。设置后会从当前主题的 theme.json 中读取同名控件配置。
tooltip string 空 鼠标悬停提示文本。
visible bool true 是否可见。为 false 时序列化会写出。
enable bool true 是否启用。为 false 时按钮进入 Disable 状态。

布局 JSON 属性

字段 类型 默认值 说明
absoluteLayout bool false 是否使用绝对停靠布局。
absoluteDockHor int 0 水平方向停靠方式。0 表示左侧，1 表示中间，2 表示右侧。
absoluteDockVer int 0 垂直方向停靠方式。0 表示上方，1 表示中间，2 表示下方。
absoluteDockOffsetX int 0 绝对停靠的 X 偏移。靠右时通常使用负值。
absoluteDockOffsetY int 0 绝对停靠的 Y 偏移。
widthPolicy int 0 宽度策略。常用于容器布局中控制固定、填充或自动尺寸。
heightPolicy int 0 高度策略。常用于容器布局中控制固定、填充或自动尺寸。
minWidth int 0 最小宽度。
minHeight int 0 最小高度。
maxWidth int Qt 默认 最大宽度。
maxHeight int Qt 默认 最大高度。

attr 属性

字段 类型 默认值 说明
text string 空 按钮文本。支持语言资源 key 的读取逻辑。
hasIcon bool true 是否绘制图标。
iconPath string 空 Normal 状态图标路径。支持 Qt 资源路径和文件路径，支持 PNG/SVG。主题加载时不会覆盖业务 JSON 中的 iconPath。
hotIconPath string 空 Hot 状态图标路径。为空时继续使用 iconPath。
showText bool true 是否绘制按钮文本。
drawBackground bool true 是否绘制按钮背景。图标按钮需要透明背景时建议设为 false。
fadeEnabled bool 全局配置 是否启用 Hot/Normal 状态之间的渐变效果。默认跟随 UIGGlobalConfig.buttonFadeEnabled，全局默认关闭。
fadeDuration int 全局配置 渐变时长，单位毫秒。小于等于 0 时按 150 处理。
iconHor int 1 图标水平停靠方式。0 左，1 中，2 右。
iconVer int 1 图标垂直停靠方式。0 上，1 中，2 下。
iconX int 0 图标 X 偏移。
iconY int 0 图标 Y 偏移。
iconUseColor bool false SVG 图标是否使用控件指定颜色。为 false 时使用 SVG 原始颜色。
iconColor string FF000000 SVG 指定颜色，格式为 AARRGGBB。仅在 iconUseColor 为 true 时生效。
txtX int 0 文本 X 偏移。常用于图标+文字按钮，为图标留出空间。
txtY int 0 文本 Y 偏移。
isExtBtn bool false 是否启用扩展图标区域。用于右侧附加箭头、下拉标记等复合按钮。
extWidth int 0 扩展图标区域宽度。
extIconPath string 空 扩展区域 Normal 图标路径。
extHotIconPath string 空 扩展区域 Hot 图标路径。

style 状态配置

按钮的 style 是一个数组，每一项格式为：

[ "styleName", styleType, position ]
字段 说明
styleName 在 style.json 中定义的样式名称。
styleType 样式类型。1 表示 FillStyle 背景样式，2 表示 TextStyleDesc 文字样式。
position 状态位置。按钮背景使用 0-3，文字使用 4-7。

状态位置说明：

position 作用
0 默认状态（Normal）背景。读取后会先同步到其它背景状态。
1 悬停状态（Hot）背景。
2 按下状态（Pressed）背景。
3 禁用状态（Disable）背景。
4 默认状态（Normal）文字。读取后会先同步到其它文字状态。
5 悬停状态（Hot）文字。
6 按下状态（Pressed）文字。
7 禁用状态（Disable）文字。

FillStyle 示例

FillStyle 放在主题目录的 style.json 中，type 为 1：

{
  "type": 1,
  "name": "PrimaryButtonBg",
  "fill": true,
  "drawImg": false,
  "clr": "FF2563EB",
  "border": true,
  "borderSize": 1,
  "borderclr": "FF1D4ED8",
  "round": 6,
  "roundTopLeft": true,
  "roundTopRight": true,
  "roundBottomRight": true,
  "roundBottomLeft": true
}

常用字段：

字段 类型 默认值 说明
type int 必填 1 表示背景填充样式。
name string 必填 样式名称，供控件 style 数组引用。
fill bool true 是否填充颜色。
clr string FFFFFFFF 填充颜色，格式为 AARRGGBB。
drawImg bool true 是否绘制图片。纯色背景一般设为 false。
img string 空 背景图片资源路径。
border bool false 是否绘制边框。
borderSize int 1 边框宽度。
borderclr string FFFFFFFF 边框颜色，格式为 AARRGGBB。
round int 0 圆角半径。
roundTopLeft bool true 左上角是否使用圆角。
roundTopRight bool true 右上角是否使用圆角。
roundBottomRight bool true 右下角是否使用圆角。
roundBottomLeft bool true 左下角是否使用圆角。
leftBorder bool true 是否绘制左边框。
topBorder bool true 是否绘制上边框。
rightBorder bool true 是否绘制右边框。
bottomBorder bool true 是否绘制下边框。

使用建议

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

输入框控件

输入框控件

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

输入框控件支持按状态配置背景和文字样式，支持 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 绘制实现对象：

类型 作用
QLineEdit Qt 标准单行输入框基类，提供文本输入、光标、选择、焦点和输入事件。
IUIGQWidgetBase WidgetKit 控件统一接口，提供主题名、布局策略、JSON 读写等能力。
UIGQWidgetBase 控件通用数据对象，保存布局、主题、透明度等基础属性。
UIGQLineEditImpl 输入框专用实现，负责背景、文字、placeholder、密码模式、快捷键模式和 JSON 属性读写。

控件接口说明

构造和类型

接口 说明 参数 返回值
UIGQLineEdit(QWidget* parent = nullptr) 创建单行输入控件。 parent：父控件，可为空。 控件实例
static const char* typeName() 返回 JSON 类型名，输入框为 qtdedit。 无 const char*
QString getTypeName() const 返回当前控件类型名。来自 WidgetKit 基础接口。 无 QString

主题和 JSON

接口 说明 参数 返回值
void setThemeName(const QString& themeName) 设置主题名。常用值为 UIG_THEME_LINE_EDIT，实际字符串为 qtdedit。 themeName：主题配置名称。 void
QString getThemeName() const 获取当前主题名。 无 QString
bool readJsonValue(void* value) 从 Json::Value 读取控件配置。通常由页面加载或设计器调用。 value：指向 Json::Value 的配置对象。 bool，读取是否成功
bool serializeJsonValue(Json::Value* value, bool bRead = true) bRead=true 时读取 JSON，bRead=false 时写出 JSON。 value：JSON 对象；bRead：是否读取。 bool，序列化是否成功
QString jsonData() const 获取设计器属性中的 JSON 字符串。 无 QString
void setJsonData(const QString& data) 设置设计器属性中的 JSON 字符串，并在首次设置时读取配置。 data：JSON 字符串。 void

背景和状态样式

接口 说明 参数 返回值
void setBackground(CtrlState state, const FillStyle& style) 设置某个状态的背景样式。state 可传 UIG_NORMAL、UIG_HOT、UIG_PRESSED、UIG_DISABLE。 state：控件状态；style：背景填充样式。 void
const FillStyle& getBackground(CtrlState state) 获取某个状态的背景样式。 state：控件状态。 const FillStyle&
void setTextStyle(CtrlState state, const TextStyleDesc& style) 设置某个状态的输入文字样式。设置 UIG_NORMAL 时会立即应用字体和颜色。 state：控件状态；style：文字样式描述。 void
const TextStyleDesc& getTextStyle(CtrlState state) 获取某个状态的输入文字样式。 state：控件状态。 const TextStyleDesc&
void setPlaceholderTextStyle(CtrlState state, const TextStyleDesc& style) 设置 placeholder 文本样式。当前实现使用一份 placeholder 样式，state 参数用于保持接口一致。 state：控件状态；style：placeholder 文字样式。 void
const TextStyleDesc& getPlaceholderTextStyle(CtrlState state) 获取 placeholder 文本样式。 state：控件状态。 const TextStyleDesc&

文本和输入模式

接口 说明 参数 返回值
void setText(const QString& text) Qt 标准接口，设置输入框文本。 text：输入框文本。 void
QString text() const Qt 标准接口，获取输入框文本。 无 QString
void setPlaceholderText(const QString& text) 设置 placeholder 文本。WidgetKit 自绘 placeholder，不依赖 Qt 原生 placeholder 绘制。 text：placeholder 文本。 void
const QString& getPlaceholderText() 获取 placeholder 文本。 无 const QString&
void setIsPassword(bool password) 设置密码模式。启用后会禁用右键菜单，并使用 QLineEdit::Password 回显模式。 password：是否启用密码模式。 void
bool getIsPassword() 获取是否为密码模式。 无 bool
void setHotkeyMode(bool hotkeyMode) 设置快捷键录入模式。 hotkeyMode：是否启用快捷键录入。 void
bool getHotkeyMode() 获取是否为快捷键录入模式。 无 bool
void setEditMargin(int top, int bottom, int left, int right) 设置输入内容边距。 top/bottom/left/right：内容边距。 void
void getEditMargin(int& top, int& bottom, int& left, int& right) 获取输入内容边距。 top/bottom/left/right：输出内容边距。 void

WidgetKit 通用布局接口

接口 说明 参数 返回值
void setLayoutRatio(int ratio) 设置布局比例值。用于比例布局。 ratio：空间占比权重。 void
int getLayoutRatio() const 获取布局比例值。 无 int
void setWidthPolicy(LayoutSizePolicy policy) 设置宽度策略。常用值为 UIG_SIZE_AUTO、UIG_SIZE_FILL、UIG_SIZE_FIXED。 policy：宽度策略枚举。 void
LayoutSizePolicy getWidthPolicy() const 获取宽度策略。 无 LayoutSizePolicy
void setHeightPolicy(LayoutSizePolicy policy) 设置高度策略。 policy：高度策略枚举。 void
LayoutSizePolicy getHeightPolicy() const 获取高度策略。 无 LayoutSizePolicy
void setAbsoluteLayout(bool absoluteLayout) 设置是否使用绝对布局。 absoluteLayout：是否启用绝对布局。 void
bool getAbsoluteLayout() const 获取是否使用绝对布局。 无 bool
void setAbsoluteDock(DockLayoutType hor, DockLayoutType ver, int offsetX = 0, int offsetY = 0) 设置绝对停靠位置和偏移。 hor：水平停靠；ver：垂直停靠；offsetX/offsetY：偏移量。 void
void getAbsoluteDock(DockLayoutType& hor, DockLayoutType& ver, int& offsetX, int& offsetY) const 获取绝对停靠位置和偏移。 hor/ver/offsetX/offsetY：输出停靠与偏移。 void
void setOpacity(int alpha) 设置控件透明度，范围 0-255。 alpha：透明度值。 void
int getOpacity() const 获取控件透明度。 无 int
void resizeWidget() 根据 WidgetKit 布局数据重新计算控件尺寸和位置。 无 void

常用信号

信号 说明 参数 返回值
void textChanged(const QString& text) Qt QLineEdit 标准信号，文本变化时触发。 text：变化后的文本。 void
void editingFinished() Qt QLineEdit 标准信号，编辑结束时触发。 无 void
void returnPressed() Qt QLineEdit 标准信号，按下回车时触发。 无 void

JSON 示例

{
  "type": "qtdedit",
  "name": "searchEdit",
  "x": 24,
  "y": 16,
  "w": 220,
  "h": 36,
  "theme": "qtdedit",
  "tooltip": "输入关键字搜索",
  "attr": {
    "text": "",
    "tip": "搜索",
    "ispassord": false,
    "shortcut": false,
    "leftMargin": 12,
    "rightMargin": 12,
    "topMargin": 8,
    "bottomMargin": 8
  },
  "style": [
    [ "editBg", 1, 0 ],
    [ "editBg", 1, 1 ],
    [ "editBg", 1, 2 ],
    [ "editDisableBg", 1, 3 ],
    [ "textLeft", 2, 4 ],
    [ "textLeft", 2, 5 ],
    [ "textLeft", 2, 6 ],
    [ "textLightGrayLeft", 2, 7 ],
    [ "textPlaceholder", 2, 9 ]
  ]
}

基础 JSON 属性

字段 类型 默认值 说明
type string 必填 控件类型，输入框固定为 qtdedit。
name string 空 Qt objectName，用于查找控件、调试和局部样式定位。
x int 0 矩形布局下的左上角 X 坐标。
y int 0 矩形布局下的左上角 Y 坐标。
w int 0 控件宽度。
h int 0 控件高度。
theme string 空 主题名。设置后会从当前主题的 theme.json 中读取同名控件配置。
tooltip string 空 鼠标悬停提示文本。
visible bool true 是否可见。为 false 时序列化会写出。
enable bool true 是否启用。为 false 时控件进入 Disable 状态。

布局 JSON 属性

字段 类型 默认值 说明
absoluteLayout bool false 是否使用绝对停靠布局。
absoluteDockHor int 0 水平方向停靠方式。0 表示左侧，1 表示中间，2 表示右侧。
absoluteDockVer int 0 垂直方向停靠方式。0 表示上方，1 表示中间，2 表示下方。
absoluteDockOffsetX int 0 绝对停靠的 X 偏移。靠右时通常使用负值。
absoluteDockOffsetY int 0 绝对停靠的 Y 偏移。
widthPolicy int 0 宽度策略。常用于容器布局中控制固定、填充或自动尺寸。
heightPolicy int 0 高度策略。常用于容器布局中控制固定、填充或自动尺寸。
minWidth int 0 最小宽度。
minHeight int 0 最小高度。
maxWidth int Qt 默认 最大宽度。
maxHeight int Qt 默认 最大高度。

attr 属性

字段 类型 默认值 说明
text string 空 输入框文本。
tip string 空 placeholder 文本。
ispassord bool false 是否密码模式。字段名来自当前代码宏，注意拼写是 ispassord。
shortcut bool false 是否快捷键录入模式。
leftMargin int 0 左侧内容边距。读取时如果只设置 leftMargin，右侧边距会先同步为同值。
rightMargin int 0 右侧内容边距。
topMargin int 0 顶部内容边距。读取时如果只设置 topMargin，底部边距会先同步为同值。
bottomMargin int 0 底部内容边距。

当前宏中还保留了一些输入框相关字段，例如 numberOnly、max、min、readonly、autoLostFocus、multi 等；UIGQLineEdit 当前实现没有读写这些字段，业务配置中暂不建议依赖。

style 状态配置

输入框的 style 是一个数组，每一项格式为：

[ "styleName", styleType, position ]
字段 说明
styleName 在 style.json 中定义的样式名称。
styleType 样式类型。1 表示 FillStyle 背景样式，2 表示 TextStyleDesc 文字样式。
position 状态位置。背景使用 0-3，输入文字使用 4-7，placeholder 使用 9。

状态位置说明：

position 作用
0 默认状态（Normal）背景。读取后会先同步到其它背景状态。
1 悬停状态（Hot）背景。
2 焦点状态（Pressed）背景，也就是获得焦点时的背景。
3 禁用状态（Disable）背景。
4 默认状态（Normal）输入文字。读取后会先同步到其它文字状态。
5 悬停状态（Hot）输入文字。
6 焦点状态（Pressed）输入文字，也就是获得焦点时的文字样式。
7 禁用状态（Disable）输入文字。
9 Placeholder 文本样式。

FillStyle 示例

FillStyle 放在主题目录的 style.json 中，type 为 1：

{
  "type": 1,
  "name": "editBg",
  "fill": true,
  "drawImg": false,
  "clr": "FFFFFFFF",
  "border": true,
  "borderSize": 1,
  "borderclr": "FFE5E7EB",
  "round": 6
}

常用字段：

字段 类型 默认值 说明
type int 必填 1 表示背景填充样式。
name string 必填 样式名称，供控件 style 数组引用。
fill bool true 是否填充颜色。
clr string FFFFFFFF 填充颜色，格式为 AARRGGBB。
drawImg bool true 是否绘制图片。纯色背景一般设为 false。
img string 空 背景图片资源路径。
border bool false 是否绘制边框。
borderSize int 1 边框宽度。
borderclr string FFFFFFFF 边框颜色，格式为 AARRGGBB。
round int 0 圆角半径。
roundTopLeft bool true 左上角是否使用圆角。
roundTopRight bool true 右上角是否使用圆角。
roundBottomRight bool true 右下角是否使用圆角。
roundBottomLeft bool true 左下角是否使用圆角。
leftBorder bool true 是否绘制左边框。
topBorder bool true 是否绘制上边框。
rightBorder bool true 是否绘制右边框。
bottomBorder bool true 是否绘制下边框。

使用建议

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

复选框控件

复选框控件

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

常见状态

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

风格参数

参数 说明
checked 是否选中
tristate 是否支持半选
label 文本说明
size 控件尺寸

类继承关系

QWidget
  └─ QCheckBox
      └─ UIGQCheckBox + IUIGQWidgetBase

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

常用方法

方法 说明 参数 返回值
setChecked(bool checked) 设置复选框是否选中。 checked：是否选中。 void
isChecked() 获取当前是否选中。 无 bool
setText(const QString& text) 设置复选框文本。 text：显示文本。 void
setThemeName(const QString& themeName) 应用复选框主题配置。 themeName：主题配置名称。 void
setShowIcon(bool show) 设置是否绘制复选框图标。 show：是否绘制图标。 void
setTristate(bool y = true) 设置是否启用三态模式。 y：是否启用三态。 void
checkState() 获取当前勾选状态。 无 Qt::CheckState

适用建议

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

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，库会自动绘制禁用态效果。
  • 文本和图标组合使用的控件，建议在示例程序中检查一次实际间距，确保当前主题下的显示效果合适。

仪表盘控件

仪表盘控件

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

常见能力

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

风格参数

参数 说明
minValue 最小值
maxValue 最大值
value 当前值
unit 单位
status normal、warning、danger

适用建议

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

授权说明

授权说明

WidgetKit 提供社区免费版、年度授权版和永久授权版。

社区免费版

适合个人学习、控件效果体验和技术选型验证。

年度授权版

适合单项目集成，包含 1 年内版本更新权益。

永久授权版

适合产品线长期复用，包含永久版本更新权益。

说明

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