269 lines
6.4 KiB
Markdown
269 lines
6.4 KiB
Markdown
# 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`
|
||
|
||
---
|
||
|
||
## 对接层级
|
||
|
||
```text
|
||
L1 UI 层（Button/Panel/Dialog）
|
||
-> L2 Manager 层（业务编排）
|
||
-> L3 Engine 组件（统一封装）
|
||
-> L4 iflow-engine-base（底层能力）
|
||
```
|
||
|
||
---
|
||
|
||
## A. 对外 API（EngineManager）
|
||
|
||
对外稳定入口：`bimEngine.engine`
|
||
|
||
```ts
|
||
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` 已提供：
|
||
|
||
```ts
|
||
protected get engineComponent(): Engine | null;
|
||
```
|
||
|
||
### 示例：剖切盒
|
||
|
||
```ts
|
||
this.engineComponent?.activeSection('box');
|
||
this.engineComponent?.setSectionBoxRange(range);
|
||
this.engineComponent?.deactivateSection();
|
||
```
|
||
|
||
### 示例：漫游
|
||
|
||
```ts
|
||
this.engineComponent?.activateFirstPersonMode();
|
||
this.engineComponent?.setWalkSpeed(speed);
|
||
this.engineComponent?.deactivateFirstPersonMode();
|
||
```
|
||
|
||
---
|
||
|
||
## C. 非 Manager 组件对接
|
||
|
||
适用于 toolbar 按钮、独立组件（如 `WalkPathPanel`）：
|
||
|
||
```ts
|
||
registry.engine3d?.getEngineComponent()?.CameraGoHome();
|
||
registry.engine3d?.getEngineComponent()?.activateZoomBox();
|
||
registry.engine3d?.getEngineComponent()?.toggleMiniMap();
|
||
```
|
||
|
||
---
|
||
|
||
## D. 原始事件对接（替代 getEngine）
|
||
|
||
`Engine.getEngine()` 已删除，改为事件桥接：
|
||
|
||
```ts
|
||
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`
|
||
|
||
```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`
|
||
|
||
```ts
|
||
protected onDialogCreated(): void {
|
||
this.engineComponent?.activateXx();
|
||
}
|
||
|
||
protected onBeforeDestroy(): void {
|
||
this.engineComponent?.deactivateXx();
|
||
}
|
||
```
|
||
|
||
### Step 3: 若是非 Manager 组件，走 getEngineComponent
|
||
|
||
```ts
|
||
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 架构
|
||
|
||
```text
|
||
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 第三方注入预设
|
||
|
||
```typescript
|
||
// 初始化设置管理器
|
||
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 调用链
|
||
|
||
```text
|
||
// 用户点击设置按钮
|
||
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 设置相关事件
|
||
|
||
```typescript
|
||
// 预设保存
|
||
bimEngine.on('setting:preset-saved', ({ preset, currentSettings, timestamp }) => {
|
||
// 可持久化到 localStorage 或后端
|
||
});
|
||
|
||
// 预设切换
|
||
bimEngine.on('setting:preset-changed', ({ preset, timestamp }) => {
|
||
// 可埋点上报
|
||
});
|
||
|
||
// 预设删除
|
||
bimEngine.on('setting:preset-deleted', (preset) => {
|
||
// 清理存储
|
||
});
|
||
```
|
||
|
||
### H.5 详细文档
|
||
|
||
- [设置系统模块文档](MODULES/设置系统.md) - 完整 API 和接入指南
|
||
|
||
---
|
||
|
||
## G. 验收清单
|
||
|
||
重构或新增功能后，至少检查：
|
||
|
||
1. `EngineManager` 是否只保留必要公共 API
|
||
2. Manager 层是否统一走 `engineComponent`
|
||
3. 是否无 `getEngine()` 调用
|
||
4. 事件订阅是否成对 `onRawEvent/offRawEvent`
|
||
5. `npm run build` 是否通过
|