LumaxForge
ZH EN

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

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

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

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

  1. 坐标系是否匹配 SeriesType

    2. - Cartesian2D：Line/Bar/Scatter/Heatmap - Polar2D：Radar

  1. 是否真的有数据

    2. - series.Count > 0 - 该 Serie seriesData.Count > 0

  1. 轴类型是否匹配数据含义

    2. - Category 轴：labels 非空；数据点 x/y 使用索引（0/1/2...） - Value 轴：x/y 为连续数值

  1. 是否存在 NaN / Infinity
  1. Value 轴范围是否把数据排除在外

    2. - 检查是否固定了 min/max - 检查 autoRangeMin/autoRangeMax 是否关闭

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

可能原因

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

你应该怎么做

  1. 在 Inspector 找到 series -> 展开某个 Serie
  2. 检查：

    3. - visible 是否为 true - seriesData 是否有元素

  3. 检查坐标系：

    4. - Radar -> coordinateSystem = Polar2D - Line/Bar/Scatter/Heatmap -> coordinateSystem = Cartesian2D

  4. 如果是 Value 轴：

    5. - 先把范围相关的“固定 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. 再逐步加入你的业务约束：

    3. - 柱状图常用：minValue=0 + autoRangeMax=true

  3. 如果你看到很多奇怪的小数刻度：

    4. - 优先设置 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. 如果你需要固定范围：

    4. - 合理设置 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