使用指南
使用指南
ChartKit 的调用模型是“控件 + 数据结构 + 主题”。业务代码只需要准备分类、数值、点位或切片数据，再交给对应图表控件。
基类能力
所有当前 ChartKit 图表都继承 UIGQChartBase，并提供以下通用能力：
| 方法 | 说明 | 参数 | 返回值 |
|---|---|---|---|
setThemePreset(UIGQChartThemePreset preset) |
使用内置主题预设。 | preset：kChartThemeDefault、kChartThemeMacarons、kChartThemeShine、kChartThemeDark。 |
void |
getThemePreset() |
读取当前主题预设。 | 无。 | UIGQChartThemePreset |
setTheme(const UIGQChartTheme& theme) |
使用自定义主题结构。 | theme：图表主题结构，包含背景、坐标轴、网格线、调色板等。 |
void |
getTheme() |
读取当前主题结构。 | 无。 | const UIGQChartTheme& |
setLegendPosition(UIGQChartLegendPosition position) |
设置图例位置。 | position：kChartLegendTop、kChartLegendRight、kChartLegendBottom、kChartLegendLeft。 |
void |
getLegendPosition() |
读取当前图例位置。 | 无。 | UIGQChartLegendPosition |
setBackgroundColor(const QColor& color) |
设置图表控件背景色。 | color：背景颜色。 |
void |
getBackgroundColor() |
读取图表控件背景色。 | 无。 | QColor |
setAnimationEnabled(bool enabled) |
开启或关闭动画。 | enabled：是否启用动画。 |
void |
getAnimationEnabled() |
读取动画开关状态。 | 无。 | bool |
setAnimationDuration(int durationMs) |
设置动画时长。 | durationMs：动画时长，单位毫秒。 |
void |
getAnimationDuration() |
读取动画时长。 | 无。 | int |
restartAnimation() |
数据更新后重新播放动画。 | 无。 | void |
getAnimationProgress() |
读取当前动画进度。 | 无。 | qreal |
setTooltipOverlay(const QPoint& anchorPos, const QString& text) |
设置 tooltip overlay。 | anchorPos：提示框锚点；text：提示文本。 |
void |
clearTooltipOverlay() |
清除 tooltip overlay。 | 无。 | void |
hasTooltipOverlay() |
判断当前是否存在 tooltip overlay。 | 无。 | bool |
drawTooltipOverlay(QPainter& painter) |
绘制 tooltip overlay，通常由图表内部调用。 | painter：绘制对象。 |
void |
数据调用规范
| 图表类型 | 主要数据结构 | 推荐入口 |
|---|---|---|
| 折线图 | UIGQLineChartSeries |
setCategories(...) + setSeries(...) |
| 柱状图 | UIGQBarChartSeries |
setCategories(...) + setSeries(...) |
| 饼图 | UIGQOpenGLPieChartSlice |
setSlices(...) |
| 散点图 | UIGQScatterChartSeries |
setSeries(...) |
| 金融图表 | UIGQFinancialKLineData / UIGQFinancialMinuteData |
setKLineData(...) / setMinuteData(...) |
推荐调用流程
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()用于清空当前数据。- 金融图表使用
setChartType(...)切换 K 线、分时和成交量显示模式。 setSeriesVisible(index, visible)用于在不删除数据的情况下控制序列显示。- 主题相关设置建议放在初始化或全局主题切换流程中。
调用边界
当前 ChartKit 不以 QtCharts 内部对象作为业务调用入口。业务侧只需要维护数据结构、主题和交互参数，图表内部渲染对象由控件自行管理。