热力图（Heatmap）

本章目标：把热力图在 EasyChart 里的“坐标/格子如何映射、SeriesData 字段怎么解释、颜色范围怎么算”的规则讲清楚，并标明它是 Pro 功能。

1. 适用场景

• 二维矩阵数据展示（行/列）
• 密度/强度可视化

2. 重要说明（Pro 功能）

• SerieType.Heatmap 的渲染器由 EasyChartProBootstrap 注册。
• 如果没有安装/启用 EasyChartPro：该 serie 会被当作“动态渲染器”尝试创建，但通常不会显示。

3. 最小可用配置（Checklist）

1. ChartProfile.coordinateSystem = Cartesian2D
2. 轴（Axis Settings）
   • 最常用：X=Category（列），Y=Category（行）
   • 也支持 X/Y 使用 Value 轴（见第 6 节）
3. Series
   • 添加 1 条 Serie
   • Serie.type = Heatmap
   • Serie.seriesData 至少 1 个点

4. Inspector 对应字段

• Series
  • series[i].type = Heatmap
  • series[i].settings：实际类型为 HeatmapSettings
    • renderMode：Grid / Gradient / Contour
    • cellGapPx
    • xSplitCount / ySplitCount（当 X/Y 使用 Value 轴时用于分格）
    • autoRange / minValue / maxValue
    • lowColor / midColor / highColor
    • clamp
    • influenceMode：None / Bleed / Smooth
    • bleed / smooth / gradient / contour 子配置

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

热力图每个数据点对应一个“格子/像素区域”，运行时使用：

• X 坐标（列）：SeriesData.x
• Y 坐标（行）：SeriesData.y
• 强度值：SeriesData.value
• 颜色覆盖：如果 SeriesData.useColor = true，则直接用 SeriesData.color，跳过 low/mid/high 的插值。

注意：Heatmap 的 x/y 不接受字符串类目；Category 轴场景下仍然用“索引”。

6. 标准模板：二维 Category（X/Y）+ value 强度（最常用）

6.1 X 轴（Category：列）

• AxisType = Category
• labels = ["Col0","Col1",...]

6.2 Y 轴（Category：行）

• AxisType = Category
• labels = ["Row0","Row1",...]

6.3 数据写法

• x = 列索引（运行时会对 x 做 RoundToInt）
• y = 行索引（运行时会对 y 做 RoundToInt）
• value = 强度

6.4 重要细节：Category 轴下“格子数”与 labelPlacement

运行时会用 Axis 的 labelPlacement 决定“按 labels.Count 分格”还是“按 labels.Count-1 分格”：

• CategoryLabelPlacement.CellCenter

  • X 方向格子数 = labels.Count
  • Y 方向格子数 = labels.Count

• 其他（非 CellCenter）

  • X 方向格子数 = max(1, labels.Count - 1)
  • Y 方向格子数 = max(1, labels.Count - 1)

这会直接影响你应该填的 x/y 索引范围。

7. Value 轴热力图（X/Y 为数值轴）

当 X 或 Y 使用 AxisType.Value 时：

• 格子数量不再来自 labels，而来自：

  • X：HeatmapSettings.xSplitCount
  • Y：HeatmapSettings.ySplitCount

• SeriesData.x/y 会先根据 _xMin/_xMax、_yMin/_yMax 归一化，再映射到格子索引。

这适合做“连续值域上的密度/强度分布”。

8. 常见坑与排错

• 全部一个颜色 / 对比不明显

  • 检查 HeatmapSettings.autoRange 是否开启
  • 或者手动设定 minValue/maxValue
  • 也检查是否所有点的 value 都几乎一样

• 颜色不按 low/mid/high 来

  • 检查是否某些点启用了 useColor=true（会覆盖调色盘插值）

• 格子对不上（索引越界/偏一格）

  • 检查 Category 轴的 labelPlacement 是否为 CellCenter
  • 根据第 6.4 节确定正确的格子数与索引范围

• 格子缝太大/太密

  • 调 HeatmapSettings.cellGapPx

9. 深入参考

• 轴与范围、Series 与数据：00-WorkflowAndLibrary.md
• 常用配方：05-CommonRecipes.md
• FAQ：06-FAQ.md