bim_engine/docs/引擎API对接.md

Engine API 对接指南（2026-03）

本文档说明 SDK 层与底层 iflow-engine-base 的最新对接方式。

核心原则

1. Engine 组件是底层能力封装层（状态管理 + 参数转换 + 底层调用）
2. EngineManager 只保留少量对外公共 API，不再做全量透传
3. 内部 Manager 直接通过 this.engineComponent 调 Engine
4. 非 Manager 组件通过 registry.engine3d?.getEngineComponent() 调 Engine
5. 不暴露 raw engine 实例，事件订阅走 onRawEvent/offRawEvent

---

对接层级

L1 UI 层（Button/Panel/Dialog）
  -> L2 Manager 层（业务编排）
  -> L3 Engine 组件（统一封装）
  -> L4 iflow-engine-base（底层能力）

---

A. 对外 API（EngineManager）

对外稳定入口：bimEngine.engine

interface EngineManagerPublicApi {
  initialize(options?: Omit<EngineOptions, 'container'>): boolean;
  isInitialized(): boolean;
  loadModel(urls: string[], options?: ModelLoadOptions): void;
  pauseRendering(): void;
  resumeRendering(): void;
  getEngineComponent(): Engine | null;
  destroy(): void;
}

EngineManager 内部仍负责：

• 创建 Engine 实例
• 创建并持有 RightKeyManager
• 组装右键菜单逻辑

---

B. 内部 Manager 对接（推荐）

BaseManager 已提供：

protected get engineComponent(): Engine | null;

示例：剖切盒

this.engineComponent?.activeSection('box');
this.engineComponent?.setSectionBoxRange(range);
this.engineComponent?.deactivateSection();

示例：漫游

this.engineComponent?.activateFirstPersonMode();
this.engineComponent?.setWalkSpeed(speed);
this.engineComponent?.deactivateFirstPersonMode();

---

C. 非 Manager 组件对接

适用于 toolbar 按钮、独立组件（如 WalkPathPanel）：

registry.engine3d?.getEngineComponent()?.CameraGoHome();
registry.engine3d?.getEngineComponent()?.activateZoomBox();
registry.engine3d?.getEngineComponent()?.toggleMiniMap();

---

D. 原始事件对接（替代 getEngine）

Engine.getEngine() 已删除，改为事件桥接：

engineComponent?.onRawEvent('measure-changed', handler);
engineComponent?.offRawEvent('measure-changed', handler);

适用场景：

• 测量回调（measure-changed / measure-click）
• 剖切盒拖动回调（section-move）

---

E. 新功能对接步骤（最新模板）

Step 1: 在 Engine 组件实现能力

文件：src/components/engine/index.ts

public activateXx(): void {
  if (!this._isInitialized || !this.engine?.xxModule) return;
  this.engine.xxModule.active();
}

public deactivateXx(): void {
  if (!this._isInitialized || !this.engine?.xxModule) return;
  this.engine.xxModule.disActive();
}

Step 2: 在 Manager 中调用（不要新增 EngineManager 透传）

文件：src/managers/xx-dialog-manager.ts

protected onDialogCreated(): void {
  this.engineComponent?.activateXx();
}

protected onBeforeDestroy(): void {
  this.engineComponent?.deactivateXx();
}

Step 3: 若是非 Manager 组件，走 getEngineComponent

registry.engine3d?.getEngineComponent()?.activateXx();

Step 4: 仅当需要“对外 SDK 公共 API”时，再考虑给 EngineManager 增加方法

判定标准：

• 该能力是否需要 bimEngine.engine?.xxx() 供外部用户直接调用
• 若仅为内部链路使用，不应在 EngineManager 再包一层

---

F. 常见反模式

• ❌ 在 EngineManager 里新增大批 this.engineInstance?.xxx() 透传
• ❌ 内部 Manager 继续写 this.registry.engine3d?.xxx()
• ❌ 通过 Engine.getEngine() 暴露 raw engine

对应正确方式：

• ✅ 内部 Manager 使用 this.engineComponent?.xxx()
• ✅ 非 Manager 使用 registry.engine3d?.getEngineComponent()?.xxx()
• ✅ 原始事件使用 onRawEvent/offRawEvent

---

---

H. 设置系统对接

设置系统通过 SettingDialogManager 和 Engine 组件协作实现。

H.1 架构

SettingDialogManager (src/managers/setting-dialog-manager.ts)
  ├── UI 管理: 设置面板生命周期、预设列表展示
  ├── 预设管理: setPresetList() / applyPresetById()
  └── 设置应用: 调用 engineComponent.setSettings()

Engine 组件 (src/components/engine/index.ts)
  ├── getSettings(): 获取当前完整设置
  ├── setSettings(patch): 应用设置补丁
  └── 各类单项设置方法 (setRenderMode, setHDRBackgroundId, etc.)

H.2 第三方注入预设

// 初始化设置管理器
bimEngine.initSetting();

// 注入第三方预设
bimEngine.setting?.setPresetList([
  {
    id: 'vendor-preset',
    presetName: '供应商预设',
    isDefault: false,
    source: 'external',
    settings: {
      render: { mode: 'advanced', contrast: 60, ... },
      display: { showEdge: true, ... },
      environment: { type: 'hdr', hdrId: 'hdr-01', ... }
    }
  }
]);

H.3 设置 API 调用链

// 用户点击设置按钮
Toolbar Setting Button
  -> registry.setting.toggle()
  -> SettingDialogManager.show()
      -> createContent() 创建面板 UI
      -> 用户修改设置
      -> this.engineComponent?.setSettings(patch)
          -> Engine.setSettings()
              -> 调用底层引擎 setting 模块

// 用户切换预设
Preset Select Change
  -> SettingDialogManager.applyPresetById(id)
      -> 找到对应 preset
      -> this.engineComponent?.setSettings(preset.settings)
      -> emit('setting:preset-changed', { preset, timestamp })

// 用户保存预设
Save Preset Button
  -> 弹出命名输入框
  -> SettingDialogManager.saveAsPresetWithName(name)
      -> 组装 EngineSettingPreset
      -> emit('setting:preset-saved', { preset, currentSettings, timestamp })

H.4 设置相关事件

// 预设保存
bimEngine.on('setting:preset-saved', ({ preset, currentSettings, timestamp }) => {
  // 可持久化到 localStorage 或后端
});

// 预设切换
bimEngine.on('setting:preset-changed', ({ preset, timestamp }) => {
  // 可埋点上报
});

// 预设删除
bimEngine.on('setting:preset-deleted', (preset) => {
  // 清理存储
});

H.5 详细文档

• 设置系统模块文档 - 完整 API 和接入指南

---

G. 验收清单

重构或新增功能后，至少检查：

1. EngineManager 是否只保留必要公共 API
2. Manager 层是否统一走 engineComponent
3. 是否无 getEngine() 调用
4. 事件订阅是否成对 onRawEvent/offRawEvent
5. npm run build 是否通过