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`

```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);
```