# 圆环图（RingChart）

本章目标：说明 RingChart 的真实含义（它不是 donut pie），并把它在 EasyChart 中的 `SeriesData` 字段解释、`RingChartSettings` 配置与 Pro/基础差异对齐到运行时代码。

---

## 1. RingChart 是什么？（非常重要）

在 EasyChart 当前实现中：

- `SerieType.RingChart` 渲染的是 **多条“进度环”**（每个数据点一条环）
- 每条环都是 **完整 360° 的底环 + 一段进度弧**
- 它不是“多个 slice 分割圆周”的饼图

如果你想要“占比构成”的圆环饼图（donut pie）：

- 目前更接近 `SerieType.Pie` + `layout.innerRadius > 0`
- 但推荐仍按你的设计决定：
  - 构成占比：用 Pie
  - 多指标进度/完成率：用 RingChart

---

## 2. 重要说明（Pro 功能）

- `SerieType.RingChart` 的渲染器由 `EasyChartProBootstrap` 注册。
- 未安装/启用 Pro 时，该 serie 通常不会显示。

---

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

1. 添加 1 条 `Serie`
   - `type = RingChart`
   - `settings = RingChartSettings`
   - `seriesData` 至少 1 个点
2. 每个点的 `value > 0`

> 注意：RingChart 会忽略 `value <= 0` 的点。

---

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

RingChart 主要使用：

- `value`：环的进度“原始值”
- `name`：环的名称
- `useColor + color`：环颜色（点级颜色覆盖）
- `id`：稳定标识（用于 legend/隐藏状态，建议保持稳定）

### 4.1 Percent 模式（默认）：value 同时支持 0~1 和 0~100

当 `RingChartSettings.valueMapping.mode = Percent`（默认）时：

- `value <= 0`：该环会被过滤
- `0~1`：按比例（0.72 = 72%）
- `> 1`：按百分比（72 = 72%，运行时会除以 100）

建议：团队统一用一种写法（全 0~1 或全 0~100），避免误用。

### 4.2 Range 模式：把 value 映射到 0..1

当 `RingChartSettings.valueMapping.mode = Range` 时：

- 会先确定范围 `min/max`：
  - `autoRange=true`：从所有 ring 的 value 自动求范围
  - `autoRange=false`：使用 `minValue/maxValue`
- 再把 `value` 映射为 `(value-min)/(max-min)` 并 clamp 到 0..1

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

当 `SeriesData.name` 为空时，RingChart 会尝试从 labels 兜底：

- 若 `ChartData.CoordinateSystem == None`：不会使用 labels 兜底，最终会退回到 `Ring {i}`
- 否则优先：`Data.PolarAxes.angleAxis.labels[i]`
- 再否则：Cartesian/任意 Category 轴的 `labels[i]`
- 最终兜底：`Ring {i}`

如果你不想依赖 PolarAxes 配置，建议直接填 `SeriesData.name`。

---

## 5. Inspector 对应字段（RingChartSettings）

- `series[i].type = RingChart`
- `series[i].settings`：实际类型为 `RingChartSettings`
  - `layout`：角度/半径/内外环/留白/中心偏移
  - `valueMapping`：Percent/Range 映射规则
  - `hover`：悬停强调（Translate/Pull/Color/Stroke）
  - `legend`：RingChart 的图例设置（纯 Pie 图表时生效）
  - `showBackground/backgroundAlpha/backgroundColor`：背景环
  - `cornerRadius`：端头圆角
  - `ringGapPx`：环与环间距

### 5.1 layout（RingChartLayoutSettings）

常用字段：

- `startAngleDeg`：起始角度
- `clockwise`：顺/逆时针
- `angleRangeDeg`：默认 360；可做“半环进度”
- `outerRadius`：外半径（<=0 自动；0~1 比例；>1 像素）
- `innerRadius`：内半径（0~1 比例或像素）
- `plot.padding`：留白（避免 hover/标签被裁剪）
- `plot.centerOffset`：中心偏移

### 5.2 hover（PieHoverSettings）

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

### 5.3 背景环与间距

- `showBackground`：是否绘制背景环
- `backgroundAlpha`：背景环透明度（最终会乘到颜色 alpha 上）
- `backgroundColor`：背景环颜色（alpha=0 时会回退用 ring 本身颜色）
- `ringGapPx`：环与环的间距
- `cornerRadius`：端头圆角（受环厚度限制）

---

## 6. 图例与隐藏交互（与 Pie 共用 HiddenPieSliceIds）

- RingChart 与 Pie 共用 `ChartInteractionState.HiddenPieSliceIds`。
- 每条环的隐藏 key：优先 `SeriesData.id`，否则使用索引字符串。
- 图例条目 label 的来源受 `PieLegendSettings.source` 影响：
  - `RingSlice` 会优先从 `polarAxes.angleAxis.labels` 取名称。

---

## 7. 标签（SerieLabelSettings）

RingChart 的标签同样使用 `Serie.labelSettings`：

- `show`：是否显示
- `showName`：是否显示 name
- `decimalPlaces`：数值小数位（注意：这里显示的是原始 `value`，不是自动乘 100 的百分比文本）
- `position`：
  - `Outside`：外侧标签 + 引导线
  - `Center`：贴在环中间

---

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

- **我以为它是 donut pie，但显示不对**
  - 这是多环进度图：每个点是一条“进度环”

- **进度不对（比如填 75 结果几乎满圈）**
  - `value>1` 会按百分比除以 100
  - 如果你想 75%：用 `0.75` 或 `75`

- **某些环不显示**
  - 检查 `value <= 0` 是否被过滤

- **交互/隐藏状态不稳定**
  - 确保 `SeriesData.id` 稳定

---

## 8. 深入参考

- 饼图（构成占比）：`15-PieChart.md`
- Series 数据结构：`00-WorkflowAndLibrary.md`