bim_engine/docs/MODULES/管理器模块.md

# Managers 模块文档

## 模块概述

| 项目 | 内容 |
|------|------|
| **模块名** | managers |
| **职责** | 处理业务逻辑，协调组件交互，管理组件生命周期 |
| **公开 API** | 15 个 Manager 类 |
| **状态** | ✅ 稳定 |

## 代码地图

```
src/managers/
├── engine-manager.ts                    # 3D 引擎管理器
├── toolbar-manager.ts                   # 工具栏管理器
├── dialog-manager.ts                    # 对话框管理器
├── button-group-manager.ts              # 按钮组管理器
├── right-key-manager.ts                 # 右键菜单管理器
├── component-detail-manager.ts          # 构件详情弹窗管理器
├── construct-tree-manager-btn.ts        # 构件树管理器
├── walk-control-manager.ts              # 漫游控制管理器
├── measure-dialog-manager.ts            # 测量对话框管理器
├── section-plane-dialog-manager.ts      # 平面剖切对话框管理器
├── section-box-dialog-manager.ts        # 剖切盒对话框管理器
├── section-axis-dialog-manager.ts       # 轴向剖切对话框管理器
├── map-dialog-manager.ts                # 地图对话框管理器
├── walk-path-dialog-manager.ts          # 漫游路径对话框管理器
└── walk-plan-view-dialog-manager.ts     # 漫游平面图对话框管理器
```

## 管理器分类

### 按继承关系

```
BaseManager
├── EngineManager
├── ToolbarManager
├── DialogManager
├── ButtonGroupManager
├── RightKeyManager
├── ComponentDetailManager
├── ConstructTreeManagerBtn
└── WalkControlManager

BaseDialogManager (继承自 BaseManager)
├── MeasureDialogManager
├── SectionPlaneDialogManager
├── SectionAxisDialogManager
├── SectionBoxDialogManager
├── MapDialogManager
├── WalkPathDialogManager
└── WalkPlanViewDialogManager
```

### 按功能分类

| 类别 | 管理器 | 职责 |
|------|--------|------|
| **核心** | EngineManager | 3D 引擎管理 |
| **UI 容器** | ToolbarManager, DialogManager, ButtonGroupManager | 容器组件管理 |
| **交互** | RightKeyManager, ComponentDetailManager, ConstructTreeManagerBtn | 用户交互 |
| **3D 工具** | MeasureDialogManager, SectionPlaneDialogManager, SectionAxisDialogManager, SectionBoxDialogManager | 3D 操作工具 |
| **漫游** | WalkControlManager, WalkPathDialogManager, WalkPlanViewDialogManager, MapDialogManager | 漫游功能 |

---

## EngineManager

### 概述

管理 3D 引擎的初始化、模型加载和测量功能。

### API

```typescript
class EngineManager extends BaseManager {
  initialize(options?: EngineOptions): void;
  isInitialized(): boolean;
  loadModel(url: string, options?: ModelLoadOptions): void;
  getEngine(): any;
  CameraGoHome(): void;
  activateMeasure(mode: MeasureMode): void;
  deactivateMeasure(): void;
  getCurrentMeasureType(): MeasureMode | null;
  destroy(): void;
}
```

### 使用示例

```typescript
const engine = new EngineManager(container);
engine.initialize();
engine.loadModel('model.gltf', { autoFit: true });
engine.activateMeasure('distance');
```

---

## ToolbarManager

### 概述

管理底部工具栏的按钮配置、显示控制、主题管理。

### API

```typescript
class ToolbarManager extends BaseManager {
  addGroup(groupId: string, beforeGroupId?: string): void;
  addButton(config: ButtonConfig): void;
  setBtnActive(id: string, active?: boolean): void;
  setButtonVisibility(id: string, visible: boolean): void;
  setShowLabel(show: boolean): void;
  updateTheme(theme: ThemeConfig): void;
  setBackgroundColor(color: string): void;
  setColors(colors: ButtonGroupColors): void;
  show(): void;
  hide(): void;
  setVisible(visible: boolean): void;
  refresh(): void;
  destroy(): void;
}
```

### 使用示例

```typescript
const toolbar = new ToolbarManager(container);

toolbar.addGroup('custom-group');
toolbar.addButton({
  id: 'custom-btn',
  groupId: 'custom-group',
  type: 'button',
  label: 'Custom',
  icon: '<svg>...</svg>',
  onClick: () => console.log('Clicked')
});

toolbar.setBtnActive('custom-btn', true);
```

---

## DialogManager

### 概述

创建和管理通用对话框实例。

### API

```typescript
class DialogManager extends BaseManager {
  create(options: DialogOptions): BimDialog;
  showInfoDialog(): void;
  updateTheme(theme: ThemeConfig): void;
  destroy(): void;
}
```

### 使用示例

```typescript
const dialogManager = new DialogManager(container);

const dialog = dialogManager.create({
  title: 'My Dialog',
  content: element,
  width: 400,
  onClose: () => console.log('Closed')
});
```

---

## MeasureDialogManager

### 概述

管理测量工具的对话框和测量面板。

### API

```typescript
class MeasureDialogManager extends BaseDialogManager {
  getActiveMode(): MeasureMode;
  switchMode(mode: MeasureMode): void;
  setMeasureResult(result: MeasureResult | null): void;
  getConfig(): MeasureConfig;
  setConfig(partial: Partial<MeasureConfig>, persist?: boolean): void;
  clearAll(): void;
  openSettings(): void;
  show(): void;
  hide(): void;
  toggle(): void;
}
```

### 测量模式

| 模式 | 说明 |
|------|------|
| `distance` | 距离测量 |
| `minDistance` | 最小距离 |
| `angle` | 角度测量 |
| `elevation` | 标高测量 |
| `volume` | 体积测量 |
| `laserDistance` | 激光测距 |
| `slope` | 坡度测量 |
| `spaceVolume` | 空间体积 |

### 使用示例

```typescript
const measure = new MeasureDialogManager();
measure.show();
measure.switchMode('distance');

const config = measure.getConfig();
measure.setConfig({ unit: 'cm', precision: 1 });
```

---

## SectionPlaneDialogManager

### 概述

管理平面剖切工具对话框。

### API

```typescript
class SectionPlaneDialogManager extends BaseDialogManager {
  show(): void;
  hide(): void;
  toggle(): void;
  isOpen(): boolean;
}
```

---

## SectionAxisDialogManager

### 概述

管理轴向剖切工具对话框。

### API

```typescript
class SectionAxisDialogManager extends BaseDialogManager {
  getHiddenState(): boolean;
  setHiddenState(isHidden: boolean): void;
  getActiveAxis(): 'x' | 'y' | 'z';
  setActiveAxis(axis: 'x' | 'y' | 'z'): void;
  show(): void;
  hide(): void;
  toggle(): void;
}
```

### 使用示例

```typescript
const sectionAxis = new SectionAxisDialogManager();
sectionAxis.show();
sectionAxis.setActiveAxis('y');
```

---

## SectionBoxDialogManager

### 概述

管理剖切盒工具对话框。

### API

```typescript
class SectionBoxDialogManager extends BaseDialogManager {
  getHiddenState(): boolean;
  setHiddenState(isHidden: boolean): void;
  getReversedState(): boolean;
  setReversedState(isReversed: boolean): void;
  getRange(): SectionBoxRange;
  setRange(range: Partial<SectionBoxRange>): void;
  show(): void;
  hide(): void;
  toggle(): void;
}

interface SectionBoxRange {
  minX: number;
  maxX: number;
  minY: number;
  maxY: number;
  minZ: number;
  maxZ: number;
}
```

### 使用示例

```typescript
const sectionBox = new SectionBoxDialogManager();
sectionBox.show();

const range = sectionBox.getRange();
sectionBox.setRange({ minX: 0, maxX: 100 });
sectionBox.setReversedState(true);
```

---

## WalkControlManager

### 概述

管理漫游控制面板和相关交互。

### API

```typescript
class WalkControlManager extends BaseManager {
  init(): void;
  show(): void;
  hide(): void;
  destroy(): void;
}
```

### 事件

| 事件 | 说明 |
|------|------|
| `walk:plan-view-toggle` | 平面图切换 |
| `walk:path-mode-toggle` | 路径模式切换 |
| `walk:walk-mode-toggle` | 漫游模式切换 |
| `walk:speed-change` | 速度变化 |
| `walk:gravity-toggle` | 重力开关 |
| `walk:collision-toggle` | 碰撞开关 |

---

## ComponentDetailManager

### 概述

管理构件详情弹窗（属性展示）的显示。

### API

```typescript
class ComponentDetailManager extends BaseManager {
  init(): void;
  show(): void;
  isOpen(): boolean;
  hide(): void;
  destroy(): void;
}
```

---

## ConstructTreeManagerBtn

### 概述

管理构件树按钮和对话框。

### API

```typescript
class ConstructTreeManagerBtn extends BaseManager {
  openConstructTreeDialog(): void;
  addGroup(groupId: string, beforeGroupId?: string): void;
  addButton(config: ButtonConfig): void;
  setButtonVisibility(id: string, visible: boolean): void;
  setShowLabel(show: boolean): void;
  setVisible(visible: boolean): void;
  setBackgroundColor(color: string): void;
  setColors(colors: ButtonGroupColors): void;
  refresh(): void;
  destroy(): void;
}
```

---

## RightKeyManager

### 概述

管理右键上下文菜单。

### API

```typescript
class RightKeyManager extends BaseManager {
  registerHandler(handler: ContextMenuHandler): void;
  showMenu(x: number, y: number, items: MenuItemConfig[], groupOrder?: string[]): void;
  hide(): void;
  destroy(): void;
}

type ContextMenuHandler = (e: MouseEvent) => MenuItemConfig[];
```

### 使用示例

```typescript
const rightKey = new RightKeyManager(container);

rightKey.registerHandler((e) => [
  { id: 'view', label: 'View', onClick: () => {} },
  { id: 'delete', label: 'Delete', onClick: () => {} }
]);
```

---

## ButtonGroupManager

### 概述

创建和管理多个按钮组实例。

### API

```typescript
class ButtonGroupManager extends BaseManager {
  create(id: string, options: ButtonGroupOptions): BimButtonGroup;
  get(id: string): BimButtonGroup | undefined;
  updateTheme(theme: ThemeConfig): void;
  destroy(): void;
}
```

---

## 交互流程

### 工具栏按钮触发测量

```
ToolbarManager (按钮点击)
    ↓
MeasureDialogManager.show()
    ↓
onModeChange 事件
    ↓
EngineManager.activateMeasure(mode)
    ↓
3D 引擎进入测量模式
```

### 漫游模式激活

```
ToolbarManager (walk 按钮)
    ↓
WalkControlManager.show()
    ↓
隐藏底部工具栏
    ↓
显示漫游控制面板
```

---

## 依赖关系

所有 Manager 都依赖:
- `BaseManager` 或 `BaseDialogManager`
- `ManagerRegistry`

各 Manager 之间通过事件系统通信，避免直接依赖。

---

**文档生成时间**: 2026-01-23