LumaxForge
ZH EN

圆环图（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

    2. - 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