# WorldObjectsTree（3D 大纲视图）技术说明
## 1. 组件定位
- **配置键**：`WorldObjectsTree`- **分类**：表格类图表（`TABLES`），静态框架（`STATIC`）- **作用**：在画布上展示三维场景中「世界对象」的层级树，支持搜索、选中、样式配置；配置面板支持按节点筛选展示范围。
本组件**不通过通用图表数据拉取接口**（`useChartDataFetch` 在实现中已注释）获取业务数据，主要依赖 **Pi 客户端 / 云渲染** 下发的世界对象列表。
---
## 2. 展示数据从哪里来
运行时通过 `index.vue` 中的 `watchEffect` 决定数据源：
| 条件 | 数据来源 ||------|----------|| `hybridStore.getInClient \|\| hybridStore.getIsCloud` 为真 | `hybridStore.getClientData(PiclientDataEnum.WORLD)`，对应 Store 中的 **`worldObjects`** || 否则（普通编辑器，未连客户端） | `chartConfig.option.dataset`（默认 `null`，可配置占位数组） |
枚举定义见 `src/store/modules/hybridStore/hybridStore.d.ts`：
- `PiclientDataEnum.WORLD = 'worldObjects'`
---
## 3. `getClientData(WORLD)` 的解析逻辑
`hybridStore` 的 `getClientData` 会按环境选择：
1. 存在 `piclient[key]` 且**没有**云侧占位的 `pageLoadData` 时：返回 **`piclient.worldObjects`**2. 存在 `hybridCloudStore.pageLoadData` 时：返回 **`pageLoadData.params?.worldObjects`**3. 否则：返回空数组 `[]`
因此：**本地客户端**以 `piclient.worldObjects` 为主；**云渲染**在部分流程下以 `pageLoadData.params.worldObjects` 为主。
---
## 4. 三维对象数据如何进入 Store
在 `hybridStore.initHybridData` 中监听 **`page.loadCompleted`**：
- 若事件携带 `data.params02.worldObjects`，会**合并**到 `piclient.worldObjects`（首次赋值或追加）。
云渲染相关逻辑还会通过 `hybridCloudStore.setPageLoadData` / `setWorldObjects` 维护 **`pageLoadData.params.worldObjects`**。
**结论**：业务上的「三维元素」列表由 **Pi 客户端（或云页面）在页面加载完成后通过事件下发**，不是编辑器内 REST 接口直接拉取。
本地开发可参考 `MockClient`、`mockData` 等模拟数据。
---
## 5. 扁平数据如何变成树
工具函数：`src/utils/threeDWorld.ts` 中的 **`convertListToTree`**。
单条记录约定字段（与 `n-tree` 配置一致）：
| 字段 | 说明 ||------|------|| `name` | 节点唯一键（`key-field`） || `displayName` | 展示名称（`label-field`） || `parent` | 父节点 `name`；根节点为 `null` |
组件内对数据使用 `cloneDeep`，避免直接修改 Store 中的引用。
---
## 6. 配置面板「数据筛选」
`config.vue` 与主组件使用**相同的数据源规则**（客户端/云用 `worldObjects`，否则用 `option.dataset`）。
用户在配置树中勾选节点后，结果写入 **`option.checkedKeys`**：
- `checkedKeys === null`：运行时展示**完整树**- `checkedKeys` 为非空数组：运行时通过 **`getCheckedTreeNodes`** 只保留勾选节点及其祖先，再 `convertListToTree` 展示
---
## 7. 默认值与占位
`config.ts` 中 **`dataset` 默认为 `null`**；仓库内 `data.json` 为示例占位结构，默认未挂载到 `option`。
无有效数组时，界面根据是否在客户端/云显示空状态或提示文案。
---
## 8. 数据流示意
```mermaidflowchart LR subgraph sources [数据源] A[page.loadCompleted.params02.worldObjects] B[pageLoadData.params.worldObjects] C[option.dataset 编辑器占位] end subgraph store [Hybrid Store] P[piclient.worldObjects] PL[pageLoadData.params] end A --> P A --> PL B --> PL subgraph getter [getClientData WORLD] G{客户端或云?} end P --> G PL --> G G -->|是| W[worldObjects 数组] C -->|否| W2[dataset] W --> T[convertListToTree] W2 --> T T --> UI[n-tree 展示]```
---
## 9. 相关文件
| 路径 | 说明 ||------|------|| `index.vue` | 画布渲染、搜索、选中、`watchEffect` 数据源与树构建 || `config.vue` | 属性配置与数据筛选树 || `config.ts` / `index.ts` | 默认 `option` 与图表元信息 || `src/store/modules/hybridStore/hybridStore.ts` | `getClientData`、`page.loadCompleted` 合并 `worldObjects` || `src/store/modules/hybridCloudStore/hybridCloudStore.ts` | 云渲染 `pageLoadData` / `worldObjects` || `src/utils/threeDWorld.ts` | `convertListToTree`、`getCheckedTreeNodes` |
---
## 10. 扩展与注意
- 若需**编辑器内无客户端**也能预览完整树，应向 `option.dataset` 注入与运行时相同结构的扁平数组。- 注释掉的 `object.*` 事件与 `reloadPiclientData` 等可用于后续「场景对象变更时自动刷新列表」，当前以 `page.loadCompleted` 灌入为主。