快速接入

快速开始

本节使用真实的 ChartKit 公开接口创建一个折线图。ChartKit 图表控件本身就是 QWidget，可直接放入 Qt Widget 页面、布局或 Qt-UI 容器中。

1. 引入头文件

#include "UIGQLineChart.h"
#include "UIGQChartTheme.h"

如果需要其它图表类型，引入对应头文件：

#include "UIGQBarChart.h"
#include "UIGQOpenGLPieChart.h"
#include "UIGQScatterChart.h"

2. 创建图表

using namespace UIGQtLib;

auto* chart = new UIGQLineChart(parent);
chart->setMinimumSize(640, 360);
chart->setTitle("Monthly Orders");

调用说明：

3. 设置分类和数据

chart->setCategories({"Jan", "Feb", "Mar", "Apr", "May"});
chart->setSeries("Orders", {128, 152, 176, 163, 209}, QColor(35, 128, 224));

调用说明：

4. 设置主题和交互

chart->setThemePreset(kChartThemeMacarons);
chart->setLegendPosition(kChartLegendBottom);
chart->setTooltipMode(kChartTooltipItem);
chart->setTooltipVisible(true);
chart->setHoverEnabled(true);
chart->setAnimationEnabled(true);

调用说明：

5. 更新数据

业务数据变化时，不要操作内部 QtCharts 对象，直接重新设置 ChartKit 数据：

chart->setSeries("Orders", latestValues, QColor(35, 128, 224));
chart->restartAnimation();

restartAnimation() 用于在数据刷新后重新播放图表动画。

使用指南

使用指南

ChartKit 的调用模型是“控件 + 数据结构 + 主题”。业务代码只需要准备分类、数值、点位或切片数据，再交给对应图表控件。

基类能力

所有当前 ChartKit 图表都继承 UIGQChartBase，并提供以下通用能力：

数据调用规范

推荐调用流程

auto* chart = new UIGQBarChart(parent);

chart->setTitle("Policy Status");
chart->setCategories({"Active", "Expiring", "Invalid"});

QVector<UIGQBarChartSeries> series;
UIGQBarChartSeries item;
item.name = "Policies";
item.values = {420, 15, 30};
item.fillColor = QColor(35, 128, 224);
series.append(item);

chart->setSeries(series);
chart->setThemePreset(kChartThemeShine);
chart->setTooltipVisible(true);
chart->setHoverEnabled(true);

调用说明

• setCategories(...) 与 values 的数量应保持一致；如果数量不同，图表会按可绘制的数据范围处理，业务侧仍建议保持一致。
• 多序列图表使用 QVector<UIGQLineChartSeries> 或 QVector<UIGQBarChartSeries>，不要重复访问内部 series。
• clearSeries() / clearSlices() 用于清空当前数据。
• setSeriesVisible(index, visible) 用于在不删除数据的情况下控制序列显示。
• 主题相关设置建议放在初始化或全局主题切换流程中。

调用边界

当前 ChartKit 不以 QtCharts 内部对象作为业务调用入口。业务侧只需要维护数据结构、主题和交互参数，图表内部渲染对象由控件自行管理。

折线图

Line Chart 折线图

折线图用于展示连续数据趋势，适合监控曲线、业务指标走势、历史对比和时序数据分析。

基类与类图

QOpenGLWidget
  └─ UIGQChartBase
      └─ UIGQLineChart + IUIGQWidgetBase

UIGQLineChart 继承 UIGQChartBase 的主题、动画、图例和 tooltip 能力，并通过 IUIGQWidgetBase 接入 Qt-UI 控件体系。

数据结构

struct UIGQLineChartSeries
{
    QString name;
    QVector<double> values;
    QColor lineColor;
    QColor areaColor;
    bool showSymbol = true;
    bool smooth = false;
    bool showArea = false;
    bool visible = true;
    qreal lineWidth = 2.0;
    qreal areaOpacity = 0.22;
};

常用方法

单序列调用

using namespace UIGQtLib;

auto* chart = new UIGQLineChart(parent);
chart->setTitle("CPU Usage");
chart->setCategories({"00:00", "00:05", "00:10", "00:15"});
chart->setSeries("CPU", {22.0, 35.0, 31.0, 48.0}, QColor(35, 128, 224));
chart->setSmooth(true);
chart->setShowSymbol(true);
chart->setThemePreset(kChartThemeMacarons);
chart->setTooltipMode(kChartTooltipAxis);
chart->setTooltipVisible(true);

调用说明：

• setCategories(...) 设置横轴标签。
• setSeries(...) 设置折线名称、数值和颜色。
• setSmooth(true) 适合趋势类图表；精确折线可保持默认 false。
• kChartTooltipAxis 适合按横轴位置查看同一时刻的值。

多序列调用

QVector<UIGQLineChartSeries> series;

UIGQLineChartSeries cpu;
cpu.name = "CPU";
cpu.values = {22, 35, 31, 48};
cpu.lineColor = QColor(35, 128, 224);
cpu.showSymbol = true;
series.append(cpu);

UIGQLineChartSeries memory;
memory.name = "Memory";
memory.values = {58, 60, 63, 61};
memory.lineColor = QColor(62, 180, 98);
memory.showArea = true;
memory.areaColor = QColor(62, 180, 98, 80);
series.append(memory);

chart->setSeries(series);

调用说明：

• 多序列使用 QVector<UIGQLineChartSeries> 一次性设置。
• showArea 与 areaColor 用于面积趋势图。
• visible 可配合 setSeriesVisible(...) 做图例筛选。

柱状图

Bar Chart 柱状图

柱状图用于分类数据对比、排行、统计汇总和分组指标展示。当前公开控件类为 UIGQBarChart，文档文件名保留 column-chart.md 是为了兼容既有页面链接。

基类与类图

QOpenGLWidget
  └─ UIGQChartBase
      └─ UIGQBarChart + IUIGQWidgetBase

UIGQBarChart 继承 UIGQChartBase，通过 ChartKit 自身的数据结构绘制柱状图。业务代码只需要设置分类、序列、主题和交互参数。

数据结构

struct UIGQBarChartSeries
{
    QString name;
    QVector<double> values;
    QColor fillColor;
    QColor borderColor;
    bool visible = true;
};

常用方法

单序列调用

using namespace UIGQtLib;

auto* chart = new UIGQBarChart(parent);
chart->setTitle("Policy Overview");
chart->setCategories({"Active", "Expiring Soon", "Need Validation", "Expired"});
chart->setSeries("Policies", {420, 15, 30, 12}, QColor(35, 128, 224));
chart->setThemePreset(kChartThemeShine);
chart->setLegendPosition(kChartLegendBottom);
chart->setTooltipMode(kChartTooltipItem);
chart->setTooltipVisible(true);
chart->setHoverEnabled(true);

调用说明：

• setCategories(...) 定义每根柱子的分类名称。
• setSeries(name, values, color) 适合只有一组统计值的场景。
• kChartTooltipItem 适合查看单个柱子的分类和值。

多序列调用

QVector<UIGQBarChartSeries> series;

UIGQBarChartSeries current;
current.name = "Current";
current.values = {420, 15, 30, 12};
current.fillColor = QColor(35, 128, 224);
series.append(current);

UIGQBarChartSeries previous;
previous.name = "Previous";
previous.values = {390, 22, 28, 18};
previous.fillColor = QColor(62, 180, 98);
series.append(previous);

chart->setSeries(series);

调用说明：

• 每个 UIGQBarChartSeries 表示一组柱状数据。
• values 的顺序应与 categories 对齐。
• fillColor 控制柱子填充色，borderColor 可用于强调边框。

饼图

Pie Chart 饼图

饼图用于展示整体中的占比关系，适合构成分析、分类占用、资源分布和摘要型数据呈现。当前公开控件类为 UIGQOpenGLPieChart。

基类与类图

QOpenGLWidget
  └─ UIGQChartBase
      └─ UIGQOpenGLPieChart + IUIGQWidgetBase

数据结构

struct UIGQOpenGLPieChartSlice
{
    QString name;
    double value = 0.0;
    QColor fillColor;
    bool visible = true;
};

常用方法

基础调用

using namespace UIGQtLib;

auto* chart = new UIGQOpenGLPieChart(parent);
chart->setTitle("Traffic Sources");

QVector<UIGQOpenGLPieChartSlice> slices;

UIGQOpenGLPieChartSlice search;
search.name = "Search";
search.value = 1048;
search.fillColor = QColor(35, 128, 224);
slices.append(search);

UIGQOpenGLPieChartSlice direct;
direct.name = "Direct";
direct.value = 735;
direct.fillColor = QColor(62, 180, 98);
slices.append(direct);

chart->setSlices(slices);
chart->setThemePreset(kChartThemeMacarons);
chart->setTooltipMode(kChartTooltipItem);
chart->setTooltipVisible(true);
chart->setHoverEnabled(true);

调用说明：

• setSlices(...) 是饼图的数据入口。
• 每个 UIGQOpenGLPieChartSlice 表示一个切片。
• value 用于计算占比，业务侧不需要提前计算百分比。

环图和角度控制

chart->setInnerRadiusRatio(0.55);
chart->setAngleRange(90.0, 360.0);
chart->setLeaderLineVisible(true);

调用说明：

• setInnerRadiusRatio(0.55) 将饼图变为环图。
• setAngleRange(...) 可用于半圆图、仪表盘式占比或特殊视觉呈现。
• setLeaderLineVisible(true) 适合标签较多的构成分析图。

散点图

Scatter Chart 散点图

散点图用于观察两个变量之间的分布关系，适合相关性分析、聚类观察、异常点识别和样本分布展示。

基类与类图

QOpenGLWidget
  └─ UIGQChartBase
      └─ UIGQScatterChart + IUIGQWidgetBase

数据结构

struct UIGQScatterChartSeries
{
    QString name;
    QVector<QPointF> points;
    QColor color;
    bool visible = true;
    qreal symbolSize = 8.0;
};

常用方法

基础调用

using namespace UIGQtLib;

auto* chart = new UIGQScatterChart(parent);
chart->setTitle("Validation Samples");

QVector<UIGQScatterChartSeries> series;

UIGQScatterChartSeries passed;
passed.name = "Passed";
passed.points = {QPointF(12, 80), QPointF(18, 88), QPointF(25, 91)};
passed.color = QColor(62, 180, 98);
passed.symbolSize = 8.0;
series.append(passed);

UIGQScatterChartSeries warning;
warning.name = "Warning";
warning.points = {QPointF(10, 52), QPointF(20, 58), QPointF(28, 61)};
warning.color = QColor(232, 148, 54);
warning.symbolSize = 10.0;
series.append(warning);

chart->setSeries(series);
chart->setThemePreset(kChartThemeShine);
chart->setTooltipMode(kChartTooltipItem);
chart->setTooltipVisible(true);
chart->setHoverEnabled(true);

调用说明：

• points 中的 QPointF(x, y) 表示散点坐标。
• 每个 UIGQScatterChartSeries 表示一个分组。
• symbolSize 控制散点半径大小，适合强调不同分组。
• setSeriesVisible(...) 可用于图例筛选或用户切换分组。

授权说明

License

ChartKit provides community, annual commercial, and permanent commercial editions.

Choose the edition according to your project scope, update expectations, and support needs.