85 lines
3.0 KiB
Markdown
85 lines
3.0 KiB
Markdown
|
# Tree 组件文档
|
|||
|
|
|
|||
|
|
## 1. 组件概述
|
|||
|
|
**BimTree** 是一个通用的树形组件，支持多级嵌套、复选框、图标和自定义内容。它通常用于展示模型结构、文件目录或层级列表。
|
|||
|
|
该组件设计为被包裹在容器（如 Dialog）中，并通过 `TreeManager` 进行创建和管理。
|
|||
|
|
|
|||
|
|
## 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 (TreeManager)
|
|||
|
|
`src/managers/tree-manager.ts`
|
|||
|
|
|
|||
|
|
* `create(options: TreeOptions)`: 创建并返回一个新的 BimTree 实例。
|
|||
|
|
* `options`: 参见 `TreeOptions` 类型定义。
|
|||
|
|
|
|||
|
|
## 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;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 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
|
|||
|
|
const tree = engine.tree.create({
|
|||
|
|
data: [
|
|||
|
|
{ id: 'root', label: 'tree.root', children: [...] }
|
|||
|
|
],
|
|||
|
|
checkable: true
|
|||
|
|
});
|
|||
|
|
// 挂载到 DOM
|
|||
|
|
document.body.appendChild(tree.element);
|
|||
|
|
```
|