# Chart 图表

`AntdUI.Chart` 用于在桌面窗口中展示折线、柱状、饼图、面积、雷达等常见统计图。适合中低复杂度的业务趋势、分类占比、多系列对比。

> **颜色约定：** AntdUI 的 `System.Drawing.Color` 在 aardio 中就是 `0xAARRGGBB` 格式数值，与 GDI+、gdip 及 plus 控件运行时颜色格式相同。图表颜色属性直接写该数值，不需要调用 `System.Drawing.Color.FromArgb(...)`。
>
> 定位提醒：`Chart` 适合快速内嵌本地图表。若需要复杂交互看板、流式布局、前端现成图表生态，优先使用 `web.view` + 前端图表库。

## 最小示例：折线图

`AntdUI.Chart(winform.host)` 会自动创建 `AntdUI.BaseForm` 并填充 `custom` 宿主，一般不需要再写 `Dock = Fill`。

```aardio
import win.ui;
/*DSG{{*/
var winform = win.form(text="AntdUI Chart";right=780;bottom=460)
winform.add(
host={cls="custom";left=16;top=16;right=764;bottom=444;db=1;dl=1;dr=1;dt=1;z=1}
)
/*}}*/

import dotNet.AntdUI;

var chart = AntdUI.Chart(winform.host);
chart.Title = "周订单趋势";
chart.ChartType = AntdUI.TChartType.Line;
chart.ShowLegend = true;
chart.ShowGrid = true;
chart.ShowAxes = true;
chart.ShowTooltip = true;
chart.EnableAnimation = true;
chart.ShowXAxisLabels = true;
chart.ShowYAxisLabels = true;

var dataset = AntdUI.ChartDataset("订单量");
dataset.FillColor = 0x781677FF;
dataset.BorderColor = 0xFF1677FF;
dataset.BorderWidth = 2;
dataset.AddPoint("周一",1,35);
dataset.AddPoint("周二",2,48);
dataset.AddPoint("周三",3,42);
dataset.AddPoint("周四",4,61);
dataset.AddPoint("周五",5,55);
chart.AddDataset(dataset);
chart.RefreshChart();

winform.show();
win.loopMessage();
```

## 多系列柱状图

```aardio
import win.ui;
/*DSG{{*/
var winform = win.form(text="多系列柱状图";right=820;bottom=480)
winform.add(
host={cls="custom";left=16;top=16;right=804;bottom=464;db=1;dl=1;dr=1;dt=1;z=1}
)
/*}}*/

import dotNet.AntdUI;
import System.Drawing;

var chart = AntdUI.Chart(winform.host);
chart.Title = "本周 / 上周对比";
chart.ChartType = AntdUI.TChartType.Bar;
chart.ShowLegend = true;
chart.ShowGrid = true;
chart.ShowAxes = true;
chart.ShowTooltip = true;
chart.EnableAnimation = true;
chart.LegendPosition = System.Drawing.ContentAlignment.BottomCenter;
chart.YAxisLabelFormat = "0";

var thisWeek = AntdUI.ChartDataset("本周",0xB41677FF);
thisWeek.BorderColor = 0xFF1677FF;
thisWeek.AddPoint("一",1,12);
thisWeek.AddPoint("二",2,18);
thisWeek.AddPoint("三",3,15);
thisWeek.AddPoint("四",4,22);
thisWeek.AddPoint("五",5,19);

var lastWeek = AntdUI.ChartDataset("上周",0xA052C41A);
lastWeek.BorderColor = 0xFF52C41A;
lastWeek.AddPoint("一",1,9);
lastWeek.AddPoint("二",2,14);
lastWeek.AddPoint("三",3,11);
lastWeek.AddPoint("四",4,16);
lastWeek.AddPoint("五",5,13);

chart.AddDataset(thisWeek);
chart.AddDataset(lastWeek);
chart.RefreshChart();

winform.show();
win.loopMessage();
```

## 饼图 / 环形图

饼图、环形图、极坐标面积图通常只使用一个数据集，并关闭坐标轴与网格。

```aardio
import win.ui;
/*DSG{{*/
var winform = win.form(text="区域占比";right=720;bottom=480)
winform.add(
host={cls="custom";left=16;top=16;right=704;bottom=464;db=1;dl=1;dr=1;dt=1;z=1}
)
/*}}*/

import dotNet.AntdUI;

var chart = AntdUI.Chart(winform.host);
chart.Title = "区域占比";
chart.ChartType = AntdUI.TChartType.Pie; // 或 AntdUI.TChartType.Doughnut
chart.ShowAxes = false;
chart.ShowGrid = false;
chart.ShowLegend = true;
chart.ShowTooltip = true;
chart.EnablePieHoverValue = true;
chart.EnableAnimation = true;

var pie = AntdUI.ChartDataset("区域");

// 数据点颜色直接使用 0xAARRGGBB 数值
var east = AntdUI.ChartDataPoint("华东",1,36);
east.Color = 0xFF1677FF;
var south = AntdUI.ChartDataPoint("华南",2,24);
south.Color = 0xFF52C41A;
pie.AddPoint(east);
pie.AddPoint(south);
pie.AddPoint("华北",3,22);
pie.AddPoint("西部",4,18);

chart.AddDataset(pie);
chart.RefreshChart();

winform.show();
win.loopMessage();
```

## 气泡图

气泡图的第 4 个数值是半径，可用 `AddPoint(label,x,y,radius)`：

```aardio
import win.ui;
/*DSG{{*/
var winform = win.form(text="渠道气泡图";right=760;bottom=480)
winform.add(
host={cls="custom";left=16;top=16;right=744;bottom=464;db=1;dl=1;dr=1;dt=1;z=1}
)
/*}}*/

import dotNet.AntdUI;

var chart = AntdUI.Chart(winform.host);
chart.Title = "渠道效果";
chart.ChartType = AntdUI.TChartType.Bubble;
chart.ShowAxes = true;
chart.ShowGrid = true;
chart.ShowLegend = true;
chart.EnableAnimation = true;

var bubble = AntdUI.ChartDataset("渠道");
bubble.FillColor = 0x8C1677FF;
bubble.BorderColor = 0xFF1677FF;
bubble.AddPoint("搜索",20,35,14);
bubble.AddPoint("社媒",45,55,22);
bubble.AddPoint("线下",70,25,10);
chart.AddDataset(bubble);
chart.RefreshChart();

winform.show();
win.loopMessage();
```

## 更新数据与刷新

```aardio
chart.ClearDatasets();

var dataset = AntdUI.ChartDataset("访问量");
dataset.AddPoint("周一",1,350);
dataset.AddPoint("周二",2,420);
dataset.AddPoint("周三",3,390);
chart.AddDataset(dataset);

// 修改数据集后调用 RefreshChart 立即重绘
chart.RefreshChart();
```

- `chart.AddDataset(dataset)`：添加一个 `ChartDataset`。
- `chart.RemoveDataset(dataset)`：移除指定数据集。
- `chart.ClearDatasets()`：清空全部数据集。
- `chart.RefreshChart()`：手动刷新。
- `dataset.AddPoint(label,x,y)`：添加普通点。
- `dataset.AddPoint(label,x,y,radius)`：添加带半径的点（气泡图等）。
- `dataset.AddPoint(chartDataPoint)`：直接加入 `ChartDataPoint` 对象。
- `dataset.Clear()`：清空当前数据集中的全部点。

## 常用属性

| 成员 | 说明 |
| --- | --- |
| `ChartType` | 图表类型，见下方枚举。 |
| `Datasets` | 数据集集合（.NET `List<ChartDataset>`）。建议用 `AddDataset` 管理。索引从 `0` 开始。 |
| `Title` | 标题文本。 |
| `TitleColor` / `TitleFont` | 标题颜色与字体；颜色直接使用 `0xAARRGGBB` 数值。 |
| `ShowLegend` | 是否显示图例。 |
| `LegendPosition` | 图例位置，`System.Drawing.ContentAlignment`。 |
| `LegendPadding` | 图例内边距。 |
| `LegendBackColor` / `LegendBorderColor` | 图例背景与边框颜色，直接使用 `0xAARRGGBB` 数值。 |
| `ShowGrid` | 是否显示网格。 |
| `ShowAxes` | 是否显示坐标轴。饼图/环形图通常设为 `false`。 |
| `ShowXAxisLabels` / `ShowYAxisLabels` | 是否显示轴标签。 |
| `ShowTooltip` | 是否显示悬停提示。 |
| `EnableAnimation` | 是否启用入场动画。 |
| `AnimationDuration` | 动画时长（毫秒）。 |
| `Padding` | 图表内边距。 |
| `AxisColor` / `GridColor` | 轴线颜色与网格颜色，直接使用 `0xAARRGGBB` 数值。 |
| `XMin` / `XMax` / `YMin` / `YMax` | 轴范围；不设置时自动计算。 |
| `XAxisLabelFormat` / `YAxisLabelFormat` | 轴标签格式串，例如 `"0"`、`"0.0"`。 |
| `CursorMode` | 十字/水平/垂直光标，`AntdUI.TChartCursor`。 |
| `ShowCursorAxisValue` | 显示光标对应轴值。 |
| `EnablePieHoverValue` | 饼图悬停时显示数值。 |
| `ShowRadarValues` | 雷达图显示数值。 |
| `PieColors` | 饼图颜色数组（`System.Drawing.Color[]`）；数组元素仍直接使用 `0xAARRGGBB` 数值。也可给每个 `ChartDataPoint.Color` 单独上色。 |
| `HoveredPoint` | 当前悬停点，`ChartDataPoint`。 |

## ChartDataset

| 成员 | 说明 |
| --- | --- |
| `Label` | 图例名称。 |
| `DataPoints` | 数据点集合，索引从 `0` 开始；读取可用 `dataset.DataPoints.get_Item(0)`。 |
| `Count` | 点数量。 |
| `FillColor` | 填充色，直接使用 `0xAARRGGBB` 数值。 |
| `BorderColor` | 边框/折线色，直接使用 `0xAARRGGBB` 数值。 |
| `BorderWidth` | 边框宽度。 |
| `LegendBoxFillColor` | 图例色块颜色，直接使用 `0xAARRGGBB` 数值。 |
| `Opacity` | 透明度，`0~1`。 |
| `Visible` | 是否显示该系列。 |
| `XFormat` / `YFormat` / `RadiusFormat` | 提示文本中的数值格式。 |

构造：

```aardio
var ds1 = AntdUI.ChartDataset("系列A");
var ds2 = AntdUI.ChartDataset("系列B",0xA052C41A);
```

## ChartDataPoint

| 成员 | 说明 |
| --- | --- |
| `Label` | 标签文本。 |
| `X` / `Y` | 坐标值。 |
| `Radius` | 半径，气泡图使用。 |
| `Color` | 点/扇区颜色；aardio 中直接使用 `0xAARRGGBB` 数值。 |
| `Tooltip` | 自定义提示文本。 |
| `Visible` | 是否显示。 |

```aardio
var point = AntdUI.ChartDataPoint("华东",1,36);
point.Color = 0xFF1677FF;
point.Tooltip = "华东 36%";
dataset.AddPoint(point);
```

## 图表类型

`chart.ChartType = AntdUI.TChartType.xxx`：

| 枚举 | 说明 |
| --- | --- |
| `Line` | 折线 |
| `Spline` | 平滑折线 |
| `SteppedLine` | 阶梯折线 |
| `Area` | 面积 |
| `SplineArea` | 平滑面积 |
| `SteppedArea` | 阶梯面积 |
| `Bar` | 柱状 |
| `HorizontalBar` | 水平条形 |
| `StackedBar` | 堆叠柱状 |
| `StackedHorizontalBar` | 堆叠水平条形 |
| `Pie` | 饼图 |
| `Doughnut` | 环形图 |
| `PolarArea` | 极坐标面积 |
| `Radar` | 雷达图 |
| `Scatter` | 散点 |
| `Bubble` | 气泡 |

光标模式 `AntdUI.TChartCursor`：

- `None`
- `Cross`
- `Horizontal`
- `Vertical`

## 事件

事件签名为 `(sender,e)`：

```aardio
chart.PointClick = function(sender,e){
    var point = e.DataPoint;
    if(point){
        winform.text = string.format(
            "点击 %s  y=%s  系列索引=%s  点索引=%s",
            point.Label,point.Y,e.DatasetIndex,e.PointIndex
        );
    }
}

chart.PointHover = function(sender,e){
    if(e.DataPoint){
        winform.text = "悬停 " + e.DataPoint.Label + " = " + e.DataPoint.Y;
    }
}

chart.AreaClick = function(sender,e){
    // e.Location 为点击位置
    winform.text = "区域点击 x=" + e.Location.X + " y=" + e.Location.Y;
}
```

| 事件 | 说明 |
| --- | --- |
| `PointClick` | 点击数据点。`e.DataPoint`、`e.DatasetIndex`、`e.PointIndex`。 |
| `PointHover` | 悬停数据点。另有 `e.Location`。 |
| `AreaClick` | 点击图表空白区域。`e.Location`。 |

索引都是 .NET 风格的 **0 基**。

## 颜色写法

在 aardio 中，.NET 的 `System.Drawing.Color` 会直接转换为 `0xAARRGGBB` 格式数值，反向传给 .NET 颜色属性时也会自动转换。因此直接写 ARGB 数值即可，不需要调用 `System.Drawing.Color.FromArgb(...)`，其格式与 GDI+、plus 控件运行时颜色相同：

```aardio
dataset.FillColor = 0x781677FF;   // A=0x78，R=0x16，G=0x77，B=0xFF
dataset.BorderColor = 0xFF1677FF;
chart.GridColor = 0xFFE6E6E6;
```

注意不要把普通 GDI `COLORREF` 的 `0xBBGGRR` 与这里的 `0xAARRGGBB` 混用。

## 注意

- `AntdUI.Chart(winform.host)` 会自动挂到 `AntdUI.BaseForm` 并填充宿主；通常不要再手写 `Dock=Fill`、不要 `dotNet.setParent`。
- `Datasets`、`DataPoints` 是 .NET 集合，**索引从 0 开始**。
- 最稳妥的添加方式是 `chart.AddDataset(dataset)` 与 `dataset.AddPoint(...)`。
- 饼图/环形图可给 `ChartDataPoint.Color` 直接赋 `0xAARRGGBB` 数值；使用 `PieColors` 时，其 `Color[]` 元素也使用相同格式的数值。
- 大数据量频繁刷新时建议关闭动画（`EnableAnimation=false`），并减少跨语言逐点回调；可一次性组装完数据集再 `RefreshChart()`。
- 复杂看板、联动筛选、海量实时数据，优先考虑 `web.view` 前端图表，而不是把 `AntdUI.Chart` 做成重型方案。