109 lines
3.7 KiB
Markdown
109 lines
3.7 KiB
Markdown
# Tree 组件文档
|
||
|
||
## 1. 组件概述
|
||
**BimTree** 是一个通用的树形组件，支持多级嵌套、复选框、图标和自定义内容。它通常用于展示模型结构、文件目录或层级列表。
|
||
该组件设计为被包裹在容器（如 Dialog）中，并通过 `ModelTreeManager` 进行创建和管理。
|
||
|
||
## 2. 组件类 API (BimTree)
|
||
`src/components/tree/index.ts`
|
||
|
||
### 2.1 核心方法
|
||
* `checkNode(id: string, checked: boolean)`: 勾选/取消勾选指定节点。支持父子联动。
|
||
* `checkAll(checked: boolean)`: 全选或全不选。
|
||
* `expandNode(id: string, expanded: boolean)`: 展开/折叠指定节点。
|
||
* `expandAll(expanded: boolean)`: 展开/折叠所有层级。
|
||
* `getCheckedNodes(includeHalfChecked?: boolean)`: 获取当前所有被勾选的节点配置列表。
|
||
* `getNode(id: string)`: 获取指定 ID 的节点实例。
|
||
|
||
## 3. Manager API (ModelTreeManager)
|
||
|
||
`ModelTreeManager` 负责创建和管理 `BimTree` 实例。
|
||
|
||
### 方法
|
||
|
||
#### `createTree(options: TreeOptions): BimTree`
|
||
创建一个新的树组件实例。
|
||
|
||
- **参数**: `options` (TreeOptions) - 树组件配置
|
||
- **返回**: `BimTree` - 树组件实例
|
||
- **功能**:
|
||
- 实例化组件
|
||
- 自动绑定组件事件到全局事件总线 (`ui:tree-node-check`, `ui:tree-node-select` 等)
|
||
- 初始化组件
|
||
|
||
#### `showStructTree(data: TreeNodeConfig[], title: string): { tree: BimTree, dialog: BimDialog }`
|
||
显示带复选框的模型结构树弹窗。
|
||
|
||
#### `showSimpleTree(data: TreeNodeConfig[], title: string): { tree: BimTree, dialog: BimDialog }`
|
||
显示简单的树形弹窗 (无复选框)。
|
||
|
||
---
|
||
|
||
## 4. 类型定义
|
||
`src/components/tree/types.ts`
|
||
|
||
```typescript
|
||
interface TreeNodeConfig {
|
||
id: string;
|
||
label: string; // 翻译键
|
||
children?: TreeNodeConfig[];
|
||
checked?: boolean;
|
||
expanded?: boolean;
|
||
disabled?: boolean;
|
||
icon?: string;
|
||
data?: any; // 业务数据
|
||
}
|
||
|
||
interface TreeOptions {
|
||
data: TreeNodeConfig[];
|
||
checkable?: boolean; // 是否显示复选框
|
||
checkStrictly?: boolean; // 是否父子联动 (默认 true)
|
||
defaultExpandAll?: boolean;
|
||
indent?: number;
|
||
|
||
// 事件回调
|
||
onNodeCheck?: (node: BimTreeNode) => void;
|
||
onNodeSelect?: (node: BimTreeNode) => void;
|
||
onNodeExpand?: (node: BimTreeNode) => void;
|
||
}
|
||
```
|
||
|
||
## 5. UI 结构与样式
|
||
* **容器**: `.bim-tree` (Flex column)
|
||
* **节点**: `.bim-tree-node`
|
||
* **内容行**: `.bim-tree-node-content` (Flex row, align-center)
|
||
* **箭头**: `.bim-tree-switcher` (SVG, rotate transform)
|
||
* **复选框**: `.bim-tree-checkbox` (自定义样式, support indeterminate)
|
||
* **图标**: `.bim-tree-icon`
|
||
* **文本**: `.bim-tree-title`
|
||
* **子容器**: `.bim-tree-children` (padding-left 缩进)
|
||
|
||
## 6. 逻辑流程
|
||
1. **初始化**:
|
||
* 根据 `data` 递归创建 `BimTreeNode` 实例。
|
||
* 建立 `id -> Node` 的 Map 索引。
|
||
* 订阅主题和语言变更。
|
||
2. **联动逻辑 (Check Cascade)**:
|
||
* **向下**: 父节点状态变更 -> 递归强制设置所有子节点。
|
||
* **向上**: 子节点状态变更 -> 冒泡检查兄弟节点状态 -> 更新父节点 (Checked/Unchecked/Indeterminate)。
|
||
3. **事件**:
|
||
* 点击复选框 -> 更新状态 -> 触发联动 -> 发送 `ui:tree-node-check`。
|
||
* 点击内容 -> 发送 `ui:tree-node-select`。
|
||
|
||
## 7. 国际化支持
|
||
* 节点 `label` 必须是翻译键。
|
||
* 组件订阅 `localeManager`，语言变更时自动刷新文本。
|
||
|
||
## 8. 使用示例
|
||
```typescript
|
||
// 通过 ModelTreeManager 创建
|
||
const tree = engine.modelTree.createTree({
|
||
data: [
|
||
{ id: 'root', label: 'tree.root', children: [...] }
|
||
],
|
||
checkable: true
|
||
});
|
||
// 挂载到 DOM
|
||
document.body.appendChild(tree.element);
|
||
```
|