bim_engine/docs/components/树形控件组件-Tree.md

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

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. 使用示例

// 通过 ModelTreeManager 创建
const tree = engine.modelTree.createTree({
    data: [
        { id: 'root', label: 'tree.root', children: [...] }
    ],
    checkable: true
});
// 挂载到 DOM
document.body.appendChild(tree.element);