# FAQ（常见问题与最快排错路线）

本章目标：当你遇到“看不到/显示不对/交互怪”等问题时，能用最短路径定位原因。

---

## 0. 最快排错路线（30 秒版）

按顺序检查，通常能解决 80% 的问题：

1. **坐标系是否匹配 SeriesType**
   - Cartesian2D：Line/Bar/Scatter/Heatmap
   - Polar2D：Radar

2. **是否真的有数据**
   - `series.Count > 0`
   - 该 Serie `seriesData.Count > 0`

3. **轴类型是否匹配数据含义**
   - Category 轴：`labels` 非空；数据点 `x/y` 使用索引（0/1/2...）
   - Value 轴：`x/y` 为连续数值

4. **是否存在 NaN / Infinity**

5. **Value 轴范围是否把数据排除在外**
   - 检查是否固定了 min/max
   - 检查 `autoRangeMin/autoRangeMax` 是否关闭

---

## 1. 我点了预览但什么都没有

### 可能原因

- `seriesData` 为空
- `Serie.visible = false`
- 坐标系与 SerieType 不匹配（例如 Radar 放在 Cartesian2D）
- 轴范围不包含数据（常见于 Value 轴被手动锁死）

### 你应该怎么做

1. 在 Inspector 找到 `series` -> 展开某个 Serie
2. 检查：
   - `visible` 是否为 true
   - `seriesData` 是否有元素
3. 检查坐标系：
   - Radar -> `coordinateSystem = Polar2D`
   - Line/Bar/Scatter/Heatmap -> `coordinateSystem = Cartesian2D`
4. 如果是 Value 轴：
   - 先把范围相关的“固定 min/max”关闭
   - 让 `autoRangeMin/autoRangeMax` 都开，确认能显示后再逐步锁定

---

## 2. Category 轴有 labels，但点/柱子不在标签上

### 典型现象

- 柱子落在两个标签中间
- 折线的点对不上 A/B/C

### 快速结论

- Category 轴下，`x`（或 `y`）通常应该是 **类目索引**（0/1/2/...），而不是“随便的数值”。

### 你应该怎么做

- 检查数据点：
  - `labels[0]` 对应 `x=0`
  - `labels[1]` 对应 `x=1`
- 如果你做的是柱状图：
  - 把 `LabelPlacement` 调成 `CellCenter`

---

## 3. Value 轴范围很怪（特别大/特别小）

### 可能原因

- Value 轴被锁死范围（min/max）
- 只锁了一端但另一端的数据非常极端
- rounding/unit 把范围吸附到不合适的单位

### 你应该怎么做

1. 先把范围回退到“全自动”，确认能显示
2. 再逐步加入你的业务约束：
   - 柱状图常用：`minValue=0` + `autoRangeMax=true`
3. 如果你看到很多奇怪的小数刻度：
   - 优先设置 `labelFormat`

---

## 4. 线条断断续续/整体不渲染

### 最常见原因

- 数据中存在 NaN / Infinity

### 你应该怎么做

- 在数据源侧过滤：
  - `float.IsNaN(x/y/z)`
  - `float.IsInfinity(x/y/z)`

---

## 5. 柱状图和标签就是对不齐

### 快速结论

- 99% 是 `LabelPlacement` 没配对

### 你应该怎么做

- Bar：优先 `LabelPlacement = CellCenter`
- Line/Scatter：优先 `LabelPlacement = Tick`

---

## 6. Heatmap 全部一个颜色 / 看起来没有层次

### 可能原因

- `autoRange=false` 但 `minValue/maxValue` 设置不合理
- `clamp=false` + 极端值导致颜色被拉爆
- 数据点 `value` 全部相同（或全是 0）

### 你应该怎么做

1. 开启 `autoRange`
2. 检查数据点 `value` 是否有变化
3. 如果你需要固定范围：
   - 合理设置 `minValue/maxValue`

---

## 7. Radar 标签缺失/混乱

### 常见原因

- 维度标签来源不统一

### 推荐做法

- 每个 Radar 点：
  - `x = 维度索引`
  - `value = 数值`
  - `name = 维度名`

并确保 Radar 不依赖 Cartesian 的轴配置来取标签。

---

## 8. tooltip/hover/选中“指错点”或状态不稳定

### 常见原因

- 每次刷新数据都产生新的点标识

### 你应该怎么做

- 保证每个点的 `SeriesData.id` 稳定
- 避免每次刷新都清空再 `Guid.NewGuid()` 生成一套全新的点

---

## 9. 我不知道应该看哪一章

- 你在“创建/克隆/预览/导出”的流程阶段：看 `02-EditorWorkflow.md`
- 你在“轴/范围/对齐/单位/格式”：看 `00-WorkflowAndLibrary.md` 的第 7 节
- 你在“某种图的 data 写法/SeriesData.x/y/z”：看 `00-WorkflowAndLibrary.md` 的第 8 节
- 你只想直接照抄模板：看 `05-CommonRecipes.md`