feat(tree): implement tree component with checkbox support and manager pattern
- Added core Tree component (BimTree, BimTreeNode) - Added TreeManager for lifecycle management - Added ModelTreeManager for business logic encapsulation (Tree + Dialog) - Integrated into BimEngine and updated demos - Added internationalization support
This commit is contained in:
84
docs/components/tree.md
Normal file
84
docs/components/tree.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# 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);
|
||||
```
|
||||
Reference in New Issue
Block a user