218 lines
6.2 KiB
Markdown
218 lines
6.2 KiB
Markdown
# iflow-engine SDK 架构设计
|
||
|
||
## 概述
|
||
|
||
iflow-engine 提供三个独立引擎类，均可单独导入：
|
||
|
||
| 类 | 定位 | 内部结构 |
|
||
|---|---|---|
|
||
| `BimEngine` | 3D 完整引擎 | ManagerRegistry + 15 Managers + 20+ UI 组件 |
|
||
| `BimEngine2d` | 2D 图纸引擎 | ManagerRegistry(仅事件) + Engine2d 组件 |
|
||
| `BimEngine720` | 720° 全景引擎 | ManagerRegistry(仅事件) + Engine720 组件 |
|
||
|
||
三个类互不依赖，各自创建独立的 `ManagerRegistry` 实例。`BimEngine2d` 和 `BimEngine720` 跳过 Manager 层，直接使用底层组件。
|
||
|
||
2026-03 的核心调整：
|
||
|
||
- 新增 `BimEngine2d`、`BimEngine720` 独立类，按需导入
|
||
- `BimEngine` 变为纯 3D 引擎，不再包含 2D/720 代码
|
||
- `EngineManager` 从“大量透传”收敛为“少量公共 API + 生命周期编排”
|
||
- 内部 Manager 统一通过 `BaseManager.engineComponent` 直接访问 `Engine` 组件
|
||
- `Engine.getEngine()` 已移除，改为 `onRawEvent()/offRawEvent()` 订阅底层事件
|
||
---
|
||
|
||
## 分层结构
|
||
|
||
```text
|
||
┌───────────────────────────────────────────────────────────────────┐
|
||
│ 用户 API 入口 │
|
||
│ BimEngine (3D) BimEngine2d (2D) BimEngine720 (720°) │
|
||
└────┬──────────────────┬────────────────────┬────────────────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
ManagerRegistry ManagerRegistry ManagerRegistry
|
||
+ 15 Managers (仅事件总线) (仅事件总线)
|
||
+ 20+ UI 组件 + Engine2d 组件 + Engine720 组件
|
||
│ │ │
|
||
└──────┬───────────┴────────┬───────────┘
|
||
│ │
|
||
▼ ▼
|
||
Services (Theme/Locale) Core (EventEmitter/BaseManager)
|
||
│
|
||
▼
|
||
iflow-engine-base (createEngine / createEngine2d / createEngine720)
|
||
```
|
||
|
||
---
|
||
|
||
## ManagerRegistry 设计
|
||
|
||
`ManagerRegistry` 是 **实例模式**：每个 `BimEngine` 都创建独立 registry，支持多实例隔离。
|
||
|
||
- ✅ 无全局共享状态污染
|
||
- ✅ 多画布/多引擎实例可并行
|
||
- ✅ 事件总线隔离
|
||
|
||
关键文件：`src/core/manager-registry.ts`
|
||
|
||
---
|
||
|
||
## Engine 访问策略（最新）
|
||
|
||
### 1) 外部 SDK 用户
|
||
|
||
通过 `bimEngine.engine`（`EngineManager`）调用稳定公共 API：
|
||
|
||
- `initialize(options?)`
|
||
- `isInitialized()`
|
||
- `loadModel(urls, options?)`
|
||
- `pauseRendering()`
|
||
- `resumeRendering()`
|
||
- `destroy()`
|
||
|
||
### 2) 内部 Manager（BaseManager 子类）
|
||
|
||
通过 `BaseManager` 新增 getter：
|
||
|
||
```ts
|
||
protected get engineComponent(): Engine | null
|
||
```
|
||
|
||
直接调用 `Engine` 组件方法，例如：
|
||
|
||
```ts
|
||
this.engineComponent?.activeSection('box');
|
||
this.engineComponent?.setWalkSpeed(speed);
|
||
```
|
||
|
||
### 3) 非 Manager 组件
|
||
|
||
通过 registry 获取组件实例：
|
||
|
||
```ts
|
||
registry.engine3d?.getEngineComponent()?.toggleMiniMap();
|
||
```
|
||
|
||
---
|
||
|
||
## EngineManager 职责边界
|
||
|
||
`EngineManager` 现在聚焦在“入口能力 + 组装能力”：
|
||
|
||
1. 创建并持有 `Engine` 组件实例
|
||
2. 初始化并持有 `RightKeyManager`
|
||
3. 注册右键菜单项并编排右键行为
|
||
4. 对外暴露少量稳定 API
|
||
|
||
不再承担：
|
||
|
||
- 对 `Engine` 全量方法的 1:1 透传
|
||
|
||
关键文件：`src/managers/engine-manager.ts`
|
||
|
||
---
|
||
|
||
## 原始引擎事件订阅策略
|
||
|
||
为避免暴露底层 raw engine 实例，`Engine` 组件提供：
|
||
|
||
- `onRawEvent(event, handler)`
|
||
- `offRawEvent(event, handler)`
|
||
|
||
例如测量与剖切盒事件：
|
||
|
||
```ts
|
||
this.engineComponent?.onRawEvent('measure-changed', handler);
|
||
this.engineComponent?.offRawEvent('measure-changed', handler);
|
||
```
|
||
|
||
关键文件：`src/components/engine/index.ts`
|
||
|
||
---
|
||
|
||
## 典型调用链
|
||
|
||
### Toolbar Home
|
||
|
||
```text
|
||
Button onClick
|
||
-> registry.engine3d?.getEngineComponent()?.CameraGoHome()
|
||
-> Engine.CameraGoHome()
|
||
-> rawEngine.viewCube.CameraGoHome()
|
||
```
|
||
|
||
### Section Box
|
||
|
||
```text
|
||
SectionBoxDialogManager (BaseDialogManager)
|
||
-> this.engineComponent?.activeSection('box')
|
||
-> Engine.activeSection('box')
|
||
-> rawEngine.clipping.active('box')
|
||
```
|
||
|
||
---
|
||
|
||
## 设计收益
|
||
|
||
- 降低中间层重复代码：`EngineManager` 大幅瘦身
|
||
- 减少三层转发链：Manager 可直接访问 `Engine` 组件
|
||
- 对外 API 稳定：仍保留 `bimEngine.engine` 作为入口
|
||
- 保持封装边界：不暴露 raw engine，仅开放受控事件桥接
|
||
|
||
---
|
||
|
||
## 后续建议
|
||
|
||
当前已完成“Manager 瘦身”阶段。若后续继续演进，可考虑将 `Engine` 组件按领域继续拆分（measure/section/walk/model/scene），进一步降低单类复杂度。
|
||
|
||
---
|
||
|
||
## 2D / 720 独立引擎设计
|
||
|
||
### 设计决策
|
||
|
||
不采用“一个 BimEngine 懒加载三种引擎”的方案，而是创建三个独立类。理由：
|
||
|
||
1. **按需导入**：只用 2D 的用户不需要打包 3D 的 UI 组件
|
||
2. **职责清晰**：3D 需要完整的 Manager 层，2D/720 只需轻量封装
|
||
3. **生命周期独立**：各自 destroy() 不影响其他实例
|
||
4. **共享服务**：`themeManager` 和 `localeManager` 依然是全局单例，主题切换对所有实例生效
|
||
|
||
### BimEngine2d 结构
|
||
|
||
```text
|
||
BimEngine2d
|
||
├─ ManagerRegistry (仅事件总线)
|
||
└─ Engine2d 组件
|
||
└─ createEngine2d() (iflow-engine-base)
|
||
```
|
||
|
||
- 构造时自动初始化，无需 `initialize()` 调用
|
||
- 直接暴露 `loadDrawing()`、`getLayers()`、`setLayerVisible()` 等 API
|
||
- 不创建任何 UI 组件（toolbar、dialog 等）
|
||
|
||
### BimEngine720 结构
|
||
|
||
```text
|
||
BimEngine720
|
||
├─ ManagerRegistry (仅事件总线)
|
||
└─ Engine720 组件
|
||
└─ createEngine720() (iflow-engine-base)
|
||
```
|
||
|
||
- 构造时自动初始化，配置 fov、zoom、rotate 等参数
|
||
- 直接暴露 `loadPanorama()`、`setFov()`、`lookAt()` 等 API
|
||
- 不创建任何 UI 组件
|
||
|
||
### 多引擎切换模式
|
||
|
||
```text
|
||
同一容器同时只能有一个引擎实例。切换时：
|
||
1. current.destroy() // 销毁当前
|
||
2. new BimEngineXxx() // 创建新实例
|
||
```
|
||
|
||
---
|
||
|
||
**文档更新时间**: 2026-03-10
|