# 饼图（Pie）

本章目标：把饼图在 EasyChart 中“数据字段怎么解释、布局/聚合/图例/交互如何生效、哪些行为有隐藏前提”的规则讲清楚，并对应到 Inspector 字段。

---

## 1. 适用场景

- 展示“占比/构成”
- 强调每个分类在整体中的比例

不适合：

- 类别过多（通常 > 8~12 个会很难读）
- 需要精确对比微小差异（更建议条形图）

---

## 2. 最小可用配置（Checklist）

1. `coordinateSystem`：Pie 不依赖 Cartesian/Polar 坐标系（按你的 Profile 现有设置即可）
2. 添加 1 条 `Serie`：
   - `type = Pie`
   - `settings = PieSettings`
   - `seriesData` 至少 1 个点
3. 确保每个点的 `value > 0`

> 注意：Pie 当前会忽略 `value <= 0` 的点。

---

## 3. 重要限制（按运行时代码）

- **只绘制第一条可见 Pie serie**：当前渲染器会遍历 `Data.Series`，找到第一条 `type=Pie` 且可见的 serie 绘制后就 `break`。
- Pie 的切片隐藏状态来自 `ChartInteractionState.HiddenPieSliceIds`，会在图例点击时写入/移除。

---

## 4. SeriesData 字段解释（按运行时代码）

Pie 主要使用：

- `value`：该切片的数值（权重）
- `name`：切片名称（推荐填写）
- `useColor + color`：切片自定义颜色（可选）
- `id`：切片稳定标识（用于隐藏/交互状态，建议保持稳定）

### 4.1 最推荐写法：显式写 name + value

- `SeriesData.name = "苹果"`
- `SeriesData.value = 12`

### 4.2 name 为空时的名称来源

当 `SeriesData.name` 为空时，Pie 会尝试从 **labels** 获取名称，但有一个前提：

- 如果 `ChartData.CoordinateSystem == None`（通常是纯 Pie/无坐标系图），运行时会 **跳过 labels 兜底**，只使用 `SeriesData.name`。

在非 None 坐标系下，名称兜底顺序是：

- 优先使用 `Data.Cartesian.xAxisId` 对应的 Category 轴 labels
- 若找不到，再使用任意一个 Category 轴 labels
- 最后兜底：`Slice {index}`

> 因此：如果你不想依赖轴配置，建议直接填 `SeriesData.name`。

### 4.3 颜色来源

- 若点上 `useColor=true`：使用 `SeriesData.color`
- 否则：使用内置调色板按顺序分配

---

## 5. 常用配置（PieSettings）

Pie 的 `settings` 是 `PieSettings`，主要包含：

- `layout`：布局（角度/半径/间隙/居中偏移等）
- `hover`：悬停交互（explode）
- `aggregation`：聚合（TopN + Others）
- `legend`：Pie 专用图例配置（只在“纯 Pie 图表”场景下替代全局 legend）

### 4.1 layout（PieLayoutSettings）

常用字段：

- `startAngleDeg`：起始角度（默认 -90 让第一片从“正上方”开始）
- `clockwise`：顺时针/逆时针
- `angleRangeDeg`：角度范围（默认 360，做“半圆饼”可设 180 等）
- `outerRadius`：外半径
  - `<= 0`：自动
  - `0~1`：按控件大小比例
  - `> 1`：像素
- `innerRadius`：内半径（Pie 通常为 0；>0 会变成“中间有洞”的效果，但更推荐用 RingChart 类型做圆环）
- `innerRadiusColor`：内圈填充颜色
- `sliceGapPx`：切片间隙（像素）
- `sliceGapType`：间隙计算方式（Radial/Translate/Uniform）
- `cornerRadius`：圆角（像素，受切片厚度限制）
- `plot.padding`：留白（避免切片/外侧标签被裁剪）
- `plot.centerOffset`：中心偏移

### 4.2 hover（PieHoverSettings）

- `hover.enabled`：是否启用悬停交互
- `hover.explodeType`：
  - `Translate`：整体平移
  - `Pull`：拉伸（拉出）
  - `Color`：变亮
  - `Stroke`：描边强调
- `hover.explodeDistance`：平移/拉伸距离（像素）

### 4.3 aggregation（PieAggregationSettings）

当分类很多时，可以把小项合并为 `Others`：

- `aggregation.enabled = true`
- `keepTopN`：保留前 N 个，其余合并
- `sortByValue`：是否按 `value` 值排序后再取 TopN
- `othersName`：Others 的名称
- `useOthersColor + othersColor`：Others 颜色

> 注意：聚合只在 `keepTopN > 0` 且切片数量超过 N 时生效。

---

## 6. 图例（PieLegendSettings）与“隐藏切片”交互

当图表是“纯 Pie 图表”（只包含 Pie/RingChart/Pie3D 且没有其它类型）时：

- 图例会优先使用 `PieSettings.legend`（或 RingChartSettings/Pie3DSettings 上的 legend），而不是 `ChartData.legend`。
- 点击图例条目会切换 `HiddenPieSliceIds`：
  - 普通切片：`SeriesData.id`（若为空则用索引字符串）
  - 聚合的 Others：固定使用 `__ec_pie_others__`

`PieLegendSettings.source` 会影响“图例条目从哪里来”：

- `Slice`：每个切片一条（默认）
- `RingSlice`：为 RingChart/RingSlice 场景提供 label 来源（优先 PolarAxes.angleAxis.labels）
- `Series`：每条 serie 一条（不再是切片级）

---

## 7. 标签（SerieLabelSettings）

Pie 标签由 `Serie.labelSettings` 控制：

- `show`：是否显示
- `fontSize / color / decimalPlaces`：字体与数值格式
- `showName`：是否在标签里显示切片名称
- `position`：`Outside/Inside/Center`
- `offset`：偏移

---

## 8. 常见坑（按现象排查）

- **某些切片不显示**
  - 检查该点 `value` 是否 `<= 0`

- **切片名称不是我想要的**
  - 推荐：直接填写 `SeriesData.name`
  - 如果依赖 labels：确保你确实有一个 Category 轴并填写了 `labels`，且顺序与数据点索引一致

- **切片颜色每次不一样/难以控制**
  - 对需要固定颜色的切片：给该点设置 `useColor=true` + `color`

- **隐藏/交互状态不稳定**
  - 确保每个点的 `SeriesData.id` 稳定（不要每次刷新都重新生成一套新 id）

---

## 9. 下一章

- 圆环图（RingChart）：`16-RingChart.md`