运行时数据注入（UIToolKit）

本章介绍：在 UI Toolkit 工作流下，如何在运行时给 ChartElement 注入数据。

对应脚本：EasyChartDataSource

1. 这套方案适合什么场景？

• 你的图表是 UI Toolkit 体系（UIDocument + UXML + ChartElement）
• 你希望提供一套“业务侧更容易调用”的注入 API（labels / values / x-y / pie / ring）
• 或者你希望直接拿一段 JSON 注入（ChartFeed）

2. 快速上手（最推荐的流程）

1. 在场景里准备 UIDocument，并确保 UXML 里有 ChartElement。
2. 在挂着 UIDocument 的 GameObject 上添加组件：EasyChartDataSource。
3. 在 Inspector 里填写：
   • uiDocument
   • chartElementName（默认 main-chart，对应 UXML 中 ChartElement 的 name）
   • profile（可选，但强烈建议填：让样式/Series 类型来自你在编辑器配置好的 ChartProfile）
4. 在运行时用代码调用：
   • SetCategoryLabels(...)
   • SetSeriesValues(...) / SetSeriesXY(...)
   • 或 ApplyJson(...)

组件内部会：

• 从 UIDocument.rootVisualElement 里找到目标 ChartElement
• 必要时用 profile 初始化图表 Data
• 修改 ChartElement.Data 并调用 RefreshData()

3. Inspector 字段说明

EasyChartDataSource 的核心配置字段：

• uiDocument

  • 指向当前 UI 的 UIDocument。
  • 如果不填，脚本会尝试 GetComponent<UIDocument>()。

• chartElementName

  • 目标 ChartElement 的 name（UXML/USS 的那个 name）。默认值为 main-chart。
  • 如果你希望用 JSON 中的 chartId/chartName 自动定位，也可以让 ChartElement 的 name 与之保持一致（见第 5 节）。

• profile

  • 可选。
  • 如果赋值，组件会将 ChartElement.Profile = profile，用于初始化/保持样式、Series 结构等。

• playAnimationOnRefresh

  • 每次注入后调用 RefreshData(..., playAnimation: playAnimationOnRefresh)。

• allowCreateSeriesFromFeed

  • 当你用 JSON（ApplyJson）注入时，如果 feed 中的 series 无法匹配到现有 Serie：
    • false（默认）：不创建新 Serie，只更新匹配到的部分。
    • true：允许根据 feed 创建新的 Serie（可能触发重建 renderers）。

4. 常用注入 API（不写 JSON）

4.1 设置类目轴标签

SetCategoryLabels(labels, axisId = AxisId.XBottom)

• 会把该轴设为 Category，并覆盖 labels。

4.2 单序列 y 值（自动 x=0..n-1）

SetSeriesValues("Sales", values)

• 默认会找到/创建一条 Serie（默认类型为 Line，不强制改类型）。
• 写入 SeriesData.value，并把 SeriesData.x 设为索引。

4.3 XY 点

SetSeriesXY("Scatter", x, y)

• 把 x[] 写入 SeriesData.x，把 y[] 写入 SeriesData.value。

4.4 Pie / Ring 注入

• SetPie(serieName, names, values)

  • 强制该 Serie 为 Pie 类型。
  • 使用 SeriesData.name 作为切片名，SeriesData.value 为数值。

• SetRing(serieName, names, percents)

  • 强制该 Serie 为 RingChart 类型。
  • 使用 SeriesData.name 作为环名，SeriesData.value 为进度值。

5. JSON 注入（ChartFeed）

你可以用：ApplyJson(json)

该方法会把 JSON 解析为 ChartFeed 并应用到 ChartElement.Data。

5.1 ChartFeed 结构

{
  "chartId": "optional",
  "chartName": "optional",
  "axes": [
    {
      "axisId": "XBottom",
      "labels": ["Mon", "Tue", "Wed"]
    }
  ],
  "series": [
    {
      "serieId": "optional",
      "name": "optional",
      "type": "Line",
      "datas": [
        { "x": 0, "value": 12 },
        { "x": 1, "value": 18 }
      ]
    }
  ]
}

对应字段见运行时代码 Scripts/Runtime/Feed/ChartFeed.cs。

5.2 ChartElement 的定位规则（chartId / chartName）

ApplyJson 内部会尝试：

• 如果 feed 提供了 chartId：优先 rootVisualElement.Q<ChartElement>(chartId)
• 其次如果提供了 chartName：尝试 Q<ChartElement>(chartName)
• 都找不到才退回到 chartElementName（默认 main-chart）

因此：

• 如果你只有一个图表，保持默认值也没问题。
• 如果你一个 UI 里有多个 ChartElement，建议让每个图表的 name 与 feed 的 chartId 或 chartName 对齐。

5.3 series 匹配与类型覆盖

ApplyJson 会先检查 JSON 内是否出现过 "type":，若出现则认为你希望允许类型覆盖（allowTypeOverride=true）。

Serie 匹配规则：

• 如果 serieId 非空：按 Serie.id 匹配
• 否则如果 name 非空：按 Serie.name 匹配
• 否则（索引模式）：按 feed 的序号匹配（第 i 条对第 i 条）

当无法匹配到 Serie 时：

• allowCreateSeriesFromFeed=false（默认）：该条 feed 会被跳过（不创建）。
• allowCreateSeriesFromFeed=true：会创建新的 Serie，并使用 feed 的 type/name/serieId。

对已匹配到的 Serie：

• 仅当 allowTypeOverride=true 且不是索引模式时，才会允许覆盖 id/name/type。

6. 常见问题与排错

• 不显示 / TryGetChart 失败

  • 确认 uiDocument 赋值正确
  • 确认 UXML 中 ChartElement 的 name 与 chartElementName 一致

• JSON 解析失败

  • EasyChartDataSource 解析 JSON 时：
    • 会优先尝试 Newtonsoft（若项目里存在 Newtonsoft.Json）
    • 否则使用 Unity JsonUtility，并把 type/axisId 的字符串写法转换为枚举整数再解析
  • 建议先用一份已知能解析的 JSON（例如从编辑器 JSON 面板生成）再改。

• 注入后 Series 对不上 / 更新错了线

  • 优先使用 serieId 做稳定匹配。
  • 如果只用 name，且同名 Serie 存在多个，脚本会使用第一个并给 warning。

• JSON 想新增 Serie 但没新增

  • 把 allowCreateSeriesFromFeed 打开。