展示控件

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

控件类型

控件	子内容与能力	典型用途
`UIGQLabel`	文本、对齐方式、字体和颜色主题	标题、字段名、说明文字
`UIGQLabelEx`	扩展文本绘制、状态文本、强调显示	复杂状态文本、提示信息
`UIGQImage`	位图、GIF、SVG、SVG 原始色或指定色、拉伸绘制	头像、插图、工具图标
`UIGQSvgView`	SVG 文件加载、缩放预览、矢量画布	大图 SVG、流程图、矢量预览
`UIGQLCDNumber`	数码管显示、位数、模式	仪表读数、设备数值
`UIGQProgressBar`	线性进度、圆形进度、文本、前景和背景	任务进度、状态百分比

类继承关系

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

常用接口：

接口	说明	参数	返回值
`setText(const QString& text)`	设置显示文本。	`text`：文本。	`void`
`text() const`	获取显示文本。	无	`QString`
`setThemeName(const QString& themeName)`	绑定文本主题。	`themeName`：主题名。	`void`
`setAlignment(Qt::Alignment alignment)`	设置文本对齐。	`alignment`：Qt 对齐标志。	`void`
`setWordWrap(bool on)`	设置是否自动换行。	`on`：是否换行。	`void`
`setPixmap(const QPixmap& pixmap)`	Qt 标签图片显示。	`pixmap`：图片对象。	`void`
`setTextStyle(CtrlState state, const TextStyleDesc& style)`	设置状态文字样式。	`state`：状态；`style`：文字样式。	`void`

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

常用接口：

接口	说明	参数	返回值
`setImagePath(const QString& path)`	设置普通图片路径。	`path`：资源或文件路径。	`void`
`getImagePath() const`	获取图片路径。	无	`QString`
`setSvgPath(const QString& path)`	设置 SVG 图片路径。	`path`：资源或文件路径。	`void`
`setSvgColor(const QColor& color)`	设置 SVG 指定颜色。	`color`：目标颜色。	`void`
`setUseSvgColor(bool useColor)`	控制 SVG 是否使用指定颜色。	`useColor`：是否启用指定颜色。	`void`
`setStretchDraw(bool stretch)`	设置图片是否拉伸绘制。	`stretch`：是否拉伸。	`void`
`setMoviePath(const QString& path)`	设置 GIF 或动画图片路径。	`path`：动画路径。	`void`
`clear()`	清空当前图片。	无	`void`

UIGQSvgView

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

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

常用接口：

接口	说明	参数	返回值
`loadSvgFile(const QString& path)`	加载 SVG 文件。	`path`：SVG 路径。	`bool`
`setThemeName(const QString& themeName)`	设置画布主题。	`themeName`：主题名。	`void`
`fitInView(...)`	按视口缩放 SVG 内容。	Qt 图形视图参数。	`void`
`setScene(QGraphicsScene* scene)`	设置图形场景。	`scene`：场景对象。	`void`

UIGQLCDNumber

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

接口	说明	参数	返回值
`display(int value)`	显示整数。	`value`：数值。	`void`
`display(double value)`	显示浮点数。	`value`：数值。	`void`
`display(const QString& value)`	显示字符串。	`value`：文本。	`void`
`setDigitCount(int count)`	设置位数。	`count`：显示位数。	`void`
`setMode(QLCDNumber::Mode mode)`	设置显示模式。	`mode`：十进制、十六进制等。	`void`
`setSegmentStyle(QLCDNumber::SegmentStyle style)`	设置数码段样式。	`style`：段样式。	`void`

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

常用接口：

接口	说明	参数	返回值
`setRange(int min, int max)`	设置进度范围。	`min/max`：最小和最大值。	`void`
`setValue(int value)`	设置当前进度。	`value`：当前值。	`void`
`value() const`	获取当前进度。	无	`int`
`setShowText(bool show)`	控制是否显示文字。	`show`：是否显示。	`void`
`setTextVisible(bool visible)`	Qt 进度条文字可见性。	`visible`：是否可见。	`void`
`setCircleProgressBar(bool circle)`	设置圆形进度模式。	`circle`：是否圆形。	`void`
`setCircleAngleRange(int startAngle, int spanAngle)`	设置圆形进度角度范围。	`startAngle/spanAngle`：起始角和范围。	`void`
`setOrientation(Qt::Orientation orientation)`	设置线性进度方向。	`orientation`：水平或垂直。	`void`

使用建议

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

Qt-UI WidgetKit 展示控件

展示控件

展示控件

控件类型

类继承关系

UIGQLabel 和 UIGQLabelEx

UIGQImage

UIGQSvgView

UIGQLCDNumber

UIGQProgressBar

使用建议