bim_engine/docs/API调用链.md

# BIM Engine SDK API 调用链

本文档记录当前版本（2026-03）主要功能的真实调用路径。

## 关键更新

- `EngineManager` 不再承载 1:1 透传
- 内部 Manager 统一走 `this.engineComponent?.xxx()`
- 非 Manager 组件走 `registry.engine3d?.getEngineComponent()?.xxx()`
- `Engine.getEngine()` 已移除，事件订阅改为 `onRawEvent()/offRawEvent()`

---

## 分层调用模型

```text
L1 Button / Panel / Dialog
   -> L2 Manager (编排)
   -> L3 Engine 组件 (能力实现)
   -> L4 iflow-engine-base (底层 API)
```

说明：

- 只有“外部入口 API”仍通过 `EngineManager` 暴露
- 内部业务调用尽量不经过 `EngineManager` 透传

---

## 1) Home（回到主视角）

文件：`src/components/button-group/toolbar/buttons/home/index.ts`

```text
点击 Home
  -> registry.engine3d?.getEngineComponent()?.CameraGoHome()
  -> Engine.CameraGoHome()
  -> rawEngine.viewCube.CameraGoHome()
```

---

## 2) Zoom Box（框选放大）

文件：`src/components/button-group/toolbar/buttons/zoom-box/index.ts`

```text
点击 Zoom Box
  -> registry.engine3d?.getEngineComponent()?.activateZoomBox()
  -> Engine.activateZoomBox()
  -> rawEngine.rangeScale.active()
```

---

## 3) Map / MiniMap（小地图开关）

文件：`src/components/button-group/toolbar/buttons/map/index.ts`

```text
点击 Map
  -> registry.engine3d?.getEngineComponent()?.toggleMiniMap()
  -> Engine.toggleMiniMap()
  -> rawEngine.controlModule.toggleMiniMap()/相关底层实现
```

---

## 4) Measure（测量）

### 4.1 打开测量对话框

```text
Toolbar measure button
  -> registry.measure?.show()
  -> MeasureDialogManager.show() (BaseDialogManager)
```

### 4.2 切换测量模式

```text
MeasurePanel.onModeChange(mode)
  -> MeasureDialogManager 回调
  -> this.engineComponent?.activateMeasure(mode)
  -> Engine.activateMeasure(mode)
  -> rawEngine.measure.*
```

### 4.3 测量回调事件

```text
MeasureDialogManager.onDialogCreated()
  -> this.engineComponent?.onRawEvent('measure-changed', handler)
  -> this.engineComponent?.onRawEvent('measure-click', handler)
  -> handler 更新 MeasurePanel
```

---

## 5) Section（剖切）

### 5.1 轴向剖切

```text
SectionAxisDialogManager.onDialogCreated()
  -> this.engineComponent?.activeSection('x')
  -> Engine.activeSection('x')
  -> rawEngine.clipping.active('x')
```

### 5.2 剖切盒范围变更

```text
SectionBoxPanel.onRangeChange(range)
  -> SectionBoxDialogManager 回调
  -> this.engineComponent?.setSectionBoxRange(range)
  -> Engine.setSectionBoxRange(range)
  -> rawEngine.clipping.updateClippingValue(range)
```

### 5.3 剖切盒移动事件

```text
SectionBoxDialogManager.onDialogCreated()
  -> this.engineComponent?.onRawEvent('section-move', handler)
  -> handler 同步 UI range
```

---

## 6) Walk（第一人称 + 路径漫游）

### 6.1 第一人称模式

```text
WalkControlManager.show()
  -> this.engineComponent?.activateFirstPersonMode()
  -> Engine.activateFirstPersonMode()
  -> rawEngine.controlModule.switchFirstPersonMode()
```

### 6.2 速度 / 重力 / 碰撞

```text
WalkControlPanel 回调
  -> WalkControlManager
  -> this.engineComponent?.setWalkSpeed()/setWalkGravity()/setWalkCollision()
  -> Engine 对应方法
  -> rawEngine.controlModule 对应方法
```

### 6.3 路径漫游（非 Manager 组件）

文件：`src/components/walk-path-panel/index.ts`

```text
WalkPathPanel
  -> registry.engine3d?.getEngineComponent()?.pathRoamingXxx()
  -> Engine.pathRoamingXxx()
  -> rawEngine.pathRoaming.*
```

---

## 7) 构件树 / 构件详情

### 7.1 构件树

```text
ConstructTreeManagerBtn
  -> this.engineComponent?.getLevelTreeData()/getTypeTreeData()/...
  -> Engine 对应方法
  -> rawEngine.modelTree / modelToolModule
```

### 7.2 构件详情

```text
ComponentDetailManager
  -> this.engineComponent?.getComponentProperties(url, id, cb)
  -> Engine.getComponentProperties(...)
  -> rawEngine.modelProperties.getModelProperties(...)
```

---

## 8) 对外公共入口链路（仍走 EngineManager）

```text
外部业务代码
  -> bimEngine.engine?.loadModel(...)
  -> EngineManager.loadModel(...)
  -> Engine.loadModel(...)
  -> rawEngine.loaderModule.loadModels(...)
```

保留在 `EngineManager` 的公共 API：

- `initialize(options?)`
- `isInitialized()`
- `loadModel(urls, options?)`
- `pauseRendering()`
- `resumeRendering()`
- `getEngineComponent()`
- `destroy()`

---

## 9) 注意事项

- 旧写法 `registry.engine3d?.xxx()`（大量透传）已不再推荐
- 旧接口 `Engine.getEngine()` 已删除
- 事件订阅请统一使用 `onRawEvent/offRawEvent`
- `menu/buttons/*` 中 `registry.engine3d?.rightKey?.hide()` 仍可用（`rightKey` 保留在 `EngineManager`）