常用配方（Common Recipes）

本章目标：把常用图表的“最低可用配置”整理成可照抄的配方（Series + Axis + 常见坑），用于你快速创建/排错。

0. 开始之前：最小检查清单

当你遇到“怎么都看不到/显示很怪”时，先按顺序检查：

1. coordinateSystem 是否与 SeriesType 匹配（Cartesian2D vs Polar2D）
2. series 是否至少 1 条，且该 Serie 的 seriesData.Count > 0
3. 轴类型是否匹配数据含义：
   • Category 轴：labels 非空，且数据点的 x/y 是索引（0/1/2…）
   • Value 轴：数据点 x/y 是连续数值
4. 是否存在 NaN/Infinity
5. 是否把 Value 轴范围“锁死”了（autoRangeMin/autoRangeMax 或固定 min/max），导致数据落在范围外

1. 折线图（Line）：类目 X + 数值 Y

目标效果

• X：类目标签（A/B/C/D）
• Y：数值
• 折线按类目对齐

配方

1. coordinateSystem = Cartesian2D
2. X 轴：
   • axisType = Category
   • labels = [A, B, C, D]
   • LabelPlacement = Tick
3. Y 轴：
   • axisType = Value
   • autoRangeMin/autoRangeMax = true
4. Series：
   • type = Line
   • 数据点：x=类目索引，y=数值

数据示例（概念）：

(x=0, y=10)
(x=1, y=20)
(x=2, y=15)
(x=3, y=30)

常见坑

• 点不落在标签上：检查 x 是否从 0 开始，是否越界（labels.Count）
• 线看起来“断了/跳”：检查是否有 NaN/Infinity

2. 柱状图（Bar）：类目居中 + Y 从 0 起

目标效果

• 每个类目一个柱子
• 标签在柱子中心对齐
• Y 轴从 0 起，避免误导

配方

1. coordinateSystem = Cartesian2D
2. X 轴：
   • axisType = Category
   • labels 填类目
   • LabelPlacement = CellCenter
3. Y 轴：
   • axisType = Value
   • 固定从 0 开始（例如 minValue=0 + autoRangeMax=true，或等价字段组合）
4. Series：
   • type = Bar
   • BarSettings.barWidth 调整柱宽

数据示例：

(x=0, y=12)
(x=1, y=18)
(x=2, y=9)

常见坑

• 柱子夹在两个标签之间：把 LabelPlacement 切到 CellCenter
• 柱子太挤/太疏：调 barWidth、barGap、categoryGap

3. 并列柱（Grouped Bar）：多条 Serie 共享同一套类目

配方

• 多条 Serie，都设置 type = Bar
• 每条 Serie 都写同一套 x=类目索引
• 用 Serie.name 区分组名（图例/tooltip 会用到）

示例（概念）：

Serie A:
  (x=0, y=10) (x=1, y=12)
Serie B:
  (x=0, y=8)  (x=1, y=15)

4. 堆叠柱（Stacked Bar）：stacked + stackGroup

配方

• 需要堆叠的 Bar 系列：
  • BarSettings.stacked = true
  • BarSettings.stackGroup = "Group1"（同组会堆叠）

常见坑

• 堆叠后高度看起来不对：确认所有参与堆叠的系列 stackGroup 完全一致

5. 散点图（Scatter）：Value X/Y + hover + sizeMapping

目标效果

• X/Y 都是连续数值
• 鼠标移上去点会变大（hover）
• 点大小可按某个维度映射（sizeMapping）

配方

1. coordinateSystem = Cartesian2D
2. X/Y 轴都设为 Value
3. type = Scatter
4. 数据点：至少 x/value，可选使用 z 作为第三维
5. ScatterSettings.hover.enabled = true

常见坑

• 点太小看不见：提高 PointSettings.size
• hover 没反应：检查 HoverHighlightSettings.enabled 和 pickRadius

6. 热力图（Heatmap）：(x, y, value) 三元组

目标效果

• X/Y 是类目轴（二维标签）
• 颜色由 value 决定

配方

1. coordinateSystem = Cartesian2D
2. X 轴：Category + labels（列标签）
3. Y 轴：Category + labels（行标签）
4. type = Heatmap
5. 数据点：
   • x = 列索引
   • y = 行索引
   • value = 强度

示例（概念）：

(x=0, y=0, value=0.2)
(x=1, y=0, value=0.8)
(x=0, y=1, value=0.5)

常见坑

• 所有格子同一颜色：检查 HeatmapSettings.autoRange/minValue/maxValue/clamp
• 格子太小/太密：调 cellSizePx / cellGapPx

7. 雷达图（Radar）：维度索引 x + 数值 value

配方

1. coordinateSystem = Polar2D
2. type = Radar
3. 数据点：
   • x = 维度索引
   • value = 数值
   • name = 维度名（建议填，便于标签/tooltip）

示例：

(x=0, value=72, name="攻击")
(x=1, value=55, name="防御")
(x=2, value=90, name="速度")

常见坑

• 雷达图标签乱/缺失：确保维度标签来源一致（不要依赖 Cartesian 的 axis 配置）
• 看不到雷达：检查 coordinateSystem 是否为 Polar2D

8. 交互/tooltip 稳定性：SeriesData.id

如果你启用了选中、tooltip 或 hover，一般建议：

• 每个数据点的 SeriesData.id 保持稳定

否则当你每次刷新数据都生成一套新 id，会造成交互状态无法关联。

下一章

• 如果你希望继续写：可以新增 06-FAQ.md（常见问题 + 最快排错路线）。