> 头文件 `ZufyUICharts.h`。`ChartBase` 集中处理绘图几何、Nice 刻度、类别轴、网格、图例、调色板、内部滚动条、吸附轴、悬停/命中、Ctrl 缩放、拖动平移、进场动画;`BarChart`/`LineChart` 只实现 `DrawData`。
最小示例:
```cpp
#include "ZufyUICharts.h"
auto chart = std::make_shared<BarChart>();
chart->AddSeries(L"销量");
chart->AddCategory(L"Q1"); chart->AddCategory(L"Q2"); chart->AddCategory(L"Q3");
chart->SetSeriesValues(0, { 12.0, 30.0, 22.0 });
chart->SetWidth(420); chart->SetHeight(260); // 图表尺寸来自自身,必须显式给或给布局权值
root->AddChild(chart);
```
## ChartBase
```cpp
enum class AText { Left, Center, Right }; enum class AVert { Top, Center };
struct Series { std::wstring name; std::vector<double> values; Color color; };
inline static std::vector<Color> DefaultPalette; // 8 色
ZSignal<int,int> PointClicked; // (series, category)
ZSignal<int> CategoryClicked; // (category)
// 数据
void AddCategory(const std::wstring&);
void AddSeries(const std::wstring& name, const std::vector<double>& v = {});
void SetValue(int s, int c, double);
void SetSeriesValues(int s, const std::vector<double>&); // 重置并重播进场动画
void UpdateSeriesValues(int s, const std::vector<double>&); // 只重绘,不重播动画(实时刷新用)
void ClearData();
int CategoryCount() const; int SeriesCount() const;
// 配置
void SetPalette(const std::vector<Color>&); void SetSeriesColor(int s, Color);
void SetValueAxisRange(double min, double max); void SetValueAxisAutoRange();
void SetValueTickCount(int n); void SetValueTickStep(double);
void SetValueFormat(int decimals, const std::wstring& prefix=L"", const std::wstring& suffix=L"");
void SetShowGrid(bool); void SetShowVGrid(bool); void SetShowLegend(bool); void SetShowValues(bool);
void SetShowCategoryLabels(bool); void SetLabelFont(const FontSpec&); void SetColors(Color axis, Color grid, Color label);
void SetStickyAxes(bool); // 吸附轴(默认开)
void SetAnimationEnabled(bool); void SetAnimationDuration(float);
void SetCategoryWidth(float); void SetPlotHeight(float); void SetFitPlotSize(bool);
void SetReferenceLine(double value, const std::wstring& label=L"", Color c=...); void ClearReferenceLine();
void SetVReferenceLine(int category, const std::wstring& label=L"", Color c=...); void ClearVReferenceLine();
// 扩展点
virtual void DrawData(ID2D1RenderTarget*) = 0;
virtual void ComputeValueRange(double& lo, double& hi);
virtual void UpdateHover(float,float); virtual void OnDataClick(float,float);
virtual std::wstring HoveredText() const;
```
###block_red_start
**易错**
- 自定义 `ChartBase` 子类**必须调用 `InitScrollBars()`**(`BarChart`/`LineChart` 构造里已调),否则内部滚动条为空。
- 实时数据用 `UpdateSeriesValues`(不重播动画),别用 `SetSeriesValues`(会重置进场动画,配合 250ms 刷新会一直闪)。
- `SetValueAxisRange(min,max)` 仅当 `max>min` 生效;滚轮 `Ctrl`=缩放(0.4..3)、`Shift`=横向滚动、否则纵向;拖动位移 > 4 DIP 才判为平移。
- 折线**面积填充的基线夹在可见轴范围内**(`ValueY(clamp(0, axisMin, axisMax))`),自动量程下不会填满整块。`LineChart` 进场为左→右揭示。
###block_red_end
- **`版本`**:`SetFillWidth/Height(true)` 在父级给出约束时会铺满;无约束(`avail=FLT_MAX`)且未设尺寸时**回退默认 `420×260`**(v1.19.4 起;不再塌成 0)。图表默认拉伸权值为 0,需要它随布局铺满时用 `SetFillWidth/Height(true)` 或权值。
## BarChart
```cpp
enum class Orientation { Vertical, Horizontal }; // v1.18.0补全 Horizontal 实现
enum class StackMode { Grouped, Stacked, PercentStacked, Overlapped };
void SetOrientation(Orientation); void SetStackMode(StackMode);
void SetBarGap(float 0..0.9); void SetStackBarRatio(float 0.1..1); void SetGroupGap(float 0..0.9);
void SetCornerRadius(float); void SetBarOutline(float w, Color c=...);
void SetBarColor(int s, int c, Color); void SetSelectedCategory(int c);
```
## LineChart
```cpp
enum class Marker { None, Circle, Square };
void SetLineWidth(float); void SetSmooth(bool); void SetDashed(bool);
void SetShowMarkers(bool); void SetMarkerSize(float); void SetMarker(Marker);
void SetAreaFill(bool on, float alpha=0.25f);
```
## PieChart(独立 UIElement)
```cpp
enum class LabelMode { None, Percent, Value, LabelAndPercent };
ZSignal<int> SliceClicked;
void AddSlice(const std::wstring& label, double value, Color = auto);
void Clear(); int SliceCount() const;
void SetDonut(float ratio); // 0=饼图,0.5=环形
void SetStartAngle(float deg); void SetClockwise(bool); void SetSliceGap(float deg);
void SetLabelMode(LabelMode); void SetShowLegend(bool); void SetPalette(...);
void SetZoom(float); float GetZoom() const; // v1.18.0:滚轮缩放 0.4..4
bool OnMouseWheel(float,float) override; // 滚轮缩放;绘制半径与命中检测同用 zoom_
void SetAnimationEnabled(bool);
```
###block_red_start
**易错**
- `PieChart` 默认拉伸权值为 0,需要显式尺寸或布局权值。
- 标签带引导线,**右半边文字左对齐接在引线末端右边、左半边右对齐贴在末端左边**。
###block_red_end图表
ChartBase、BarChart、LineChart、PieChart(v1.18.0)
头文件
ZufyUICharts.h。ChartBase集中处理绘图几何、Nice 刻度、类别轴、网格、图例、调色板、内部滚动条、吸附轴、悬停/命中、Ctrl 缩放、拖动平移、进场动画;BarChart/LineChart只实现DrawData。
最小示例:
cpp
#include "ZufyUICharts.h"
auto chart = std::make_shared<BarChart>();
chart->AddSeries(L"销量");
chart->AddCategory(L"Q1"); chart->AddCategory(L"Q2"); chart->AddCategory(L"Q3");
chart->SetSeriesValues(0, { 12.0, 30.0, 22.0 });
chart->SetWidth(420); chart->SetHeight(260); // 图表尺寸来自自身,必须显式给或给布局权值
root->AddChild(chart);
ChartBase
cpp
enum class AText { Left, Center, Right }; enum class AVert { Top, Center };
struct Series { std::wstring name; std::vector<double> values; Color color; };
inline static std::vector<Color> DefaultPalette; // 8 色
ZSignal<int,int> PointClicked; // (series, category)
ZSignal<int> CategoryClicked; // (category)
// 数据
void AddCategory(const std::wstring&);
void AddSeries(const std::wstring& name, const std::vector<double>& v = {});
void SetValue(int s, int c, double);
void SetSeriesValues(int s, const std::vector<double>&); // 重置并重播进场动画
void UpdateSeriesValues(int s, const std::vector<double>&); // 只重绘,不重播动画(实时刷新用)
void ClearData();
int CategoryCount() const; int SeriesCount() const;
// 配置
void SetPalette(const std::vector<Color>&); void SetSeriesColor(int s, Color);
void SetValueAxisRange(double min, double max); void SetValueAxisAutoRange();
void SetValueTickCount(int n); void SetValueTickStep(double);
void SetValueFormat(int decimals, const std::wstring& prefix=L"", const std::wstring& suffix=L"");
void SetShowGrid(bool); void SetShowVGrid(bool); void SetShowLegend(bool); void SetShowValues(bool);
void SetShowCategoryLabels(bool); void SetLabelFont(const FontSpec&); void SetColors(Color axis, Color grid, Color label);
void SetStickyAxes(bool); // 吸附轴(默认开)
void SetAnimationEnabled(bool); void SetAnimationDuration(float);
void SetCategoryWidth(float); void SetPlotHeight(float); void SetFitPlotSize(bool);
void SetReferenceLine(double value, const std::wstring& label=L"", Color c=...); void ClearReferenceLine();
void SetVReferenceLine(int category, const std::wstring& label=L"", Color c=...); void ClearVReferenceLine();
// 扩展点
virtual void DrawData(ID2D1RenderTarget*) = 0;
virtual void ComputeValueRange(double& lo, double& hi);
virtual void UpdateHover(float,float); virtual void OnDataClick(float,float);
virtual std::wstring HoveredText() const;
易错
- 自定义
ChartBase子类必须调用InitScrollBars()(BarChart/LineChart构造里已调),否则内部滚动条为空。 - 实时数据用
UpdateSeriesValues(不重播动画),别用SetSeriesValues(会重置进场动画,配合 250ms 刷新会一直闪)。 SetValueAxisRange(min,max)仅当max>min生效;滚轮Ctrl=缩放(0.4..3)、Shift=横向滚动、否则纵向;拖动位移 > 4 DIP 才判为平移。- 折线面积填充的基线夹在可见轴范围内(
ValueY(clamp(0, axisMin, axisMax))),自动量程下不会填满整块。LineChart进场为左→右揭示。
版本:SetFillWidth/Height(true)在父级给出约束时会铺满;无约束(avail=FLT_MAX)且未设尺寸时回退默认420×260(v1.19.4 起;不再塌成 0)。图表默认拉伸权值为 0,需要它随布局铺满时用SetFillWidth/Height(true)或权值。
BarChart
cpp
enum class Orientation { Vertical, Horizontal }; // v1.18.0补全 Horizontal 实现
enum class StackMode { Grouped, Stacked, PercentStacked, Overlapped };
void SetOrientation(Orientation); void SetStackMode(StackMode);
void SetBarGap(float 0..0.9); void SetStackBarRatio(float 0.1..1); void SetGroupGap(float 0..0.9);
void SetCornerRadius(float); void SetBarOutline(float w, Color c=...);
void SetBarColor(int s, int c, Color); void SetSelectedCategory(int c);
LineChart
cpp
enum class Marker { None, Circle, Square };
void SetLineWidth(float); void SetSmooth(bool); void SetDashed(bool);
void SetShowMarkers(bool); void SetMarkerSize(float); void SetMarker(Marker);
void SetAreaFill(bool on, float alpha=0.25f);
PieChart(独立 UIElement)
cpp
enum class LabelMode { None, Percent, Value, LabelAndPercent };
ZSignal<int> SliceClicked;
void AddSlice(const std::wstring& label, double value, Color = auto);
void Clear(); int SliceCount() const;
void SetDonut(float ratio); // 0=饼图,0.5=环形
void SetStartAngle(float deg); void SetClockwise(bool); void SetSliceGap(float deg);
void SetLabelMode(LabelMode); void SetShowLegend(bool); void SetPalette(...);
void SetZoom(float); float GetZoom() const; // v1.18.0:滚轮缩放 0.4..4
bool OnMouseWheel(float,float) override; // 滚轮缩放;绘制半径与命中检测同用 zoom_
void SetAnimationEnabled(bool);
易错
PieChart默认拉伸权值为 0,需要显式尺寸或布局权值。- 标签带引导线,右半边文字左对齐接在引线末端右边、左半边右对齐贴在末端左边。