# 散点图（Scatter）

本章目标：把散点图在 EasyChart 的“数据字段约定”说清楚，尤其是 `SeriesData.y/value` 的兼容逻辑，以及 `z` 维度如何驱动 `sizeMapping`。

---

## 1. 适用场景

- 相关性分析（X/Y 两个数值维度）
- 分布展示（点云）
- 异常点识别（离群点）

---

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

1. `ChartProfile.coordinateSystem = Cartesian2D`
2. 轴
   - 常见：X=Value，Y=Value
3. Series
   - 添加 1 条 `Serie`
   - `Serie.type = Scatter`
   - `Serie.seriesData` 至少 2 个点

---

## 3. Inspector 对应字段

- `series[i].type = Scatter`
- `series[i].settings`：实际类型为 `ScatterSettings`
  - `point`：点样式（显示/大小/纹理）
  - `hover`：悬停高亮（enabled/pickRadius/scale 等，具体字段以版本为准）
  - `sizeMapping`：点大小映射

---

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

散点图渲染时使用：

- **X 坐标**：`SeriesData.x`
- **Y 坐标**：优先使用 `SeriesData.y`
  - 兼容逻辑：如果 `y == 0` 且 `value != 0`，运行时会把 `value` 当成 y 来用
- **点大小映射维度**：`SeriesData.z`（当 `sizeMapping.enabled=true` 时）

因此你有两种常见写法：

### 4.1 推荐写法（显式 X/Y）

- `x = X 值`
- `y = Y 值`

### 4.2 兼容写法（旧数据：用 value 当 y）

- `x = X 值`
- `value = Y 值`
- `y = 0`

> 建议：新数据直接写 `y`，这样不会跟“点的其他含义（value）”混在一起。

---

## 5. 标准模板：Value X + Value Y

- X 轴：`AxisType = Value`
- Y 轴：`AxisType = Value`
- 数据：使用 4.1 的写法（x/y）

---

## 6. sizeMapping（点大小映射）的真实规则

当 `ScatterSettings.sizeMapping.enabled = true` 时：

- 点半径会根据 `SeriesData.z` 映射得到
- 映射范围：`minValue/maxValue` → `minSize/maxSize`
- 若 `clamp = true`，会把超范围的 t 值夹到 0..1
- `curve` 会对 t 做一次曲线变换（用于非线性映射）

如果你发现 sizeMapping “没效果”，优先检查：

- 是否真的给了 `z` 值（默认 0）
- `minValue/maxValue` 是否相等（相等会导致映射退化）

---

## 7. 常见坑与排错

- **点全在一条水平线**
  - 你可能只填了 `value`，但又把 `y` 也写成了非 0（兼容逻辑不会触发）
  - 建议统一用 `y` 作为纵坐标

- **hover 没反应**
  - `ScatterSettings.hover.enabled` 必须开启
  - `pickRadius` 太小也会导致很难拾取

- **点太小/太大**
  - 调整 `ScatterSettings.point.size`
  - 或检查 sizeMapping 的 `minSize/maxSize`

---

## 8. 深入参考

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