提交代码
This commit is contained in:
yuding
297
docs/ENGINE_2D/API文档.md
Normal file
297
docs/ENGINE_2D/API文档.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# 2D 图纸引擎 API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
`BimEngine2d` 是独立的 2D CAD/DWG 图纸查看引擎。轻量级设计，不依赖 3D 引擎的 UI 管理器（toolbar、measure 等），构造时自动初始化。
|
||||
|
||||
**文件路径**: `src/bim-engine-2d.ts`
|
||||
**底层依赖**: `iflow-engine-base` 的 `createEngine2d()`
|
||||
|
||||
---
|
||||
|
||||
## 导入
|
||||
|
||||
```typescript
|
||||
// ESM
|
||||
import { BimEngine2d } from 'iflow-engine';
|
||||
|
||||
// UMD
|
||||
const { BimEngine2d } = IflowEngine;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## BimEngine2d
|
||||
|
||||
### 构造函数
|
||||
|
||||
```typescript
|
||||
constructor(container: HTMLElement | string, options?: BimEngine2dOptions)
|
||||
```
|
||||
|
||||
**参数**:
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `container` | `HTMLElement \| string` | ✅ | DOM 元素或元素 ID |
|
||||
| `options` | `BimEngine2dOptions` | | 构造选项 |
|
||||
|
||||
构造时自动初始化引擎，无需额外调用 `initialize()` 方法。
|
||||
|
||||
### BimEngine2dOptions
|
||||
|
||||
```typescript
|
||||
interface BimEngine2dOptions {
|
||||
/** 语言 */
|
||||
locale?: 'zh-CN' | 'en-US';
|
||||
/** 主题 */
|
||||
theme?: 'dark' | 'light';
|
||||
/** 背景颜色（十六进制数值，如 0xffffff） */
|
||||
backgroundColor?: number;
|
||||
/** 是否启用网格 */
|
||||
gridEnabled?: boolean;
|
||||
/** 是否启用坐标轴 */
|
||||
axesEnabled?: boolean;
|
||||
/** 选中构件颜色 */
|
||||
selectionColor?: number;
|
||||
/** 高亮构件颜色 */
|
||||
highlightColor?: number;
|
||||
/** 是否启用性能监控 */
|
||||
enablePerformanceMonitoring?: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 图纸操作
|
||||
|
||||
### loadDrawing()
|
||||
|
||||
```typescript
|
||||
public async loadDrawing(url: string, options?: DrawingLoadOptions): Promise<void>
|
||||
```
|
||||
|
||||
**功能**: 加载 2D 图纸
|
||||
|
||||
**参数**:
|
||||
- `url`: string — 图纸资源 URL
|
||||
- `options`: DrawingLoadOptions — 加载选项（可选）
|
||||
|
||||
**返回值**: Promise\<void\>
|
||||
|
||||
```typescript
|
||||
interface DrawingLoadOptions {
|
||||
/** 分块大小 */
|
||||
chunkSize?: number;
|
||||
/** 是否启用分块加载 */
|
||||
enableChunkedLoading?: boolean;
|
||||
/** 是否启用数据校验 */
|
||||
enableValidation?: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```typescript
|
||||
await engine2d.loadDrawing('https://example.com/drawing-id');
|
||||
```
|
||||
|
||||
### getLayers()
|
||||
|
||||
```typescript
|
||||
public getLayers(): Drawing2dLayer[]
|
||||
```
|
||||
|
||||
**功能**: 获取当前图纸的所有图层
|
||||
|
||||
**返回值**: Drawing2dLayer[]
|
||||
|
||||
```typescript
|
||||
interface Drawing2dLayer {
|
||||
/** 图层名称 */
|
||||
name: string;
|
||||
/** 图层是否可见 */
|
||||
visible: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```typescript
|
||||
const layers = engine2d.getLayers();
|
||||
layers.forEach(layer => {
|
||||
console.log(`${layer.name}: ${layer.visible ? '可见' : '隐藏'}`);
|
||||
});
|
||||
```
|
||||
|
||||
### setLayerVisible()
|
||||
|
||||
```typescript
|
||||
public setLayerVisible(name: string, visible: boolean): void
|
||||
```
|
||||
|
||||
**功能**: 设置指定图层的可见性
|
||||
|
||||
**参数**:
|
||||
- `name`: string — 图层名称
|
||||
- `visible`: boolean — 是否可见
|
||||
|
||||
**示例**:
|
||||
|
||||
```typescript
|
||||
engine2d.setLayerVisible('标注层', false); // 隐藏标注层
|
||||
engine2d.setLayerVisible('墙体', true); // 显示墙体层
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 视图控制
|
||||
|
||||
### resetView()
|
||||
|
||||
```typescript
|
||||
public resetView(): void
|
||||
```
|
||||
|
||||
**功能**: 重置视图到初始状态
|
||||
|
||||
### fitToView()
|
||||
|
||||
```typescript
|
||||
public fitToView(): void
|
||||
```
|
||||
|
||||
**功能**: 缩放到适应全部图纸内容
|
||||
|
||||
### setZoom()
|
||||
|
||||
```typescript
|
||||
public setZoom(zoom: number): void
|
||||
```
|
||||
|
||||
**功能**: 设置缩放级别
|
||||
|
||||
**参数**:
|
||||
- `zoom`: number — 缩放值
|
||||
|
||||
### getZoom()
|
||||
|
||||
```typescript
|
||||
public getZoom(): number
|
||||
```
|
||||
|
||||
**功能**: 获取当前缩放级别
|
||||
|
||||
**返回值**: number — 当前缩放值，默认 1
|
||||
|
||||
---
|
||||
|
||||
## 主题
|
||||
|
||||
### setTheme()
|
||||
|
||||
```typescript
|
||||
public setTheme(theme: 'dark' | 'light'): void
|
||||
```
|
||||
|
||||
**功能**: 切换主题
|
||||
|
||||
**参数**:
|
||||
- `theme`: 'dark' | 'light'
|
||||
|
||||
---
|
||||
|
||||
## 事件
|
||||
|
||||
### on()
|
||||
|
||||
```typescript
|
||||
public on<K extends keyof EngineEvents>(
|
||||
event: K,
|
||||
listener: (payload: EngineEvents[K]) => void
|
||||
): () => void
|
||||
```
|
||||
|
||||
**功能**: 订阅事件
|
||||
|
||||
**返回值**: 取消订阅函数
|
||||
|
||||
**示例**:
|
||||
|
||||
```typescript
|
||||
const unsub = engine2d.on('engine:model-loaded', (payload) => {
|
||||
console.log('图纸加载完成');
|
||||
});
|
||||
|
||||
// 取消订阅
|
||||
unsub();
|
||||
```
|
||||
|
||||
### off()
|
||||
|
||||
```typescript
|
||||
public off<K extends keyof EngineEvents>(
|
||||
event: K,
|
||||
listener: (payload: EngineEvents[K]) => void
|
||||
): void
|
||||
```
|
||||
|
||||
**功能**: 取消事件订阅
|
||||
|
||||
### onRawEvent()
|
||||
|
||||
```typescript
|
||||
public onRawEvent(event: string, handler: (...args: any[]) => void): void
|
||||
```
|
||||
|
||||
**功能**: 订阅底层 2D 引擎的原始事件
|
||||
|
||||
### offRawEvent()
|
||||
|
||||
```typescript
|
||||
public offRawEvent(event: string, handler: (...args: any[]) => void): void
|
||||
```
|
||||
|
||||
**功能**: 取消订阅底层 2D 引擎的原始事件
|
||||
|
||||
---
|
||||
|
||||
## 生命周期
|
||||
|
||||
### destroy()
|
||||
|
||||
```typescript
|
||||
public destroy(): void
|
||||
```
|
||||
|
||||
**功能**: 销毁引擎，释放所有资源
|
||||
|
||||
- 销毁底层 Engine2d 组件
|
||||
- 重置 ManagerRegistry
|
||||
- 调用后实例不可再使用
|
||||
|
||||
**重要**: 切换引擎类型或页面卸载时务必调用。
|
||||
|
||||
---
|
||||
|
||||
## 内部架构
|
||||
|
||||
```text
|
||||
BimEngine2d (用户 API)
|
||||
├─ ManagerRegistry (仅事件总线，不注册 Manager)
|
||||
└─ Engine2d 组件 (IBimComponent)
|
||||
└─ createEngine2d() (iflow-engine-base)
|
||||
```
|
||||
|
||||
与 `BimEngine`（3D）的关键区别：
|
||||
|
||||
| | BimEngine (3D) | BimEngine2d (2D) |
|
||||
|---|---|---|
|
||||
| Manager 层 | 15 个 Manager | 无（跳过 Manager 层） |
|
||||
| UI 组件 | toolbar、dialog、menu 等 | 无 |
|
||||
| 初始化 | 需要调用 `engine.initialize()` | 构造时自动初始化 |
|
||||
| ManagerRegistry | 完整注册所有 Manager | 仅用于事件发射 |
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: 1.0.0 | **更新日期**: 2026-03-10
|
||||
307
docs/ENGINE_720/API文档.md
Normal file
307
docs/ENGINE_720/API文档.md
Normal file
@@ -0,0 +1,307 @@
|
||||
# 720° 全景引擎 API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
`BimEngine720` 是独立的 720° 全景图查看引擎。轻量级设计，支持鼠标/触摸旋转和缩放，不依赖 3D 引擎的 UI 管理器，构造时自动初始化。
|
||||
|
||||
**文件路径**: `src/bim-engine-720.ts`
|
||||
**底层依赖**: `iflow-engine-base` 的 `createEngine720()`
|
||||
|
||||
---
|
||||
|
||||
## 导入
|
||||
|
||||
```typescript
|
||||
// ESM
|
||||
import { BimEngine720 } from 'iflow-engine';
|
||||
|
||||
// UMD
|
||||
const { BimEngine720 } = IflowEngine;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## BimEngine720
|
||||
|
||||
### 构造函数
|
||||
|
||||
```typescript
|
||||
constructor(container: HTMLElement | string, options?: BimEngine720Options)
|
||||
```
|
||||
|
||||
**参数**:
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `container` | `HTMLElement \| string` | ✅ | DOM 元素或元素 ID |
|
||||
| `options` | `BimEngine720Options` | | 构造选项 |
|
||||
|
||||
构造时自动初始化引擎，无需额外调用 `initialize()` 方法。
|
||||
|
||||
### BimEngine720Options
|
||||
|
||||
```typescript
|
||||
interface BimEngine720Options {
|
||||
/** 语言 */
|
||||
locale?: 'zh-CN' | 'en-US';
|
||||
/** 主题 */
|
||||
theme?: 'dark' | 'light';
|
||||
/** 视场角（默认 75） */
|
||||
fov?: number;
|
||||
/** 是否启用缩放（默认 true） */
|
||||
enableZoom?: boolean;
|
||||
/** 是否启用旋转（默认 true） */
|
||||
enableRotate?: boolean;
|
||||
/** 球体半径（默认 500） */
|
||||
sphereRadius?: number;
|
||||
/** 旋转速度 */
|
||||
rotateSpeed?: number;
|
||||
/** 缩放速度 */
|
||||
zoomSpeed?: number;
|
||||
/** 是否启用阻尼（惯性效果） */
|
||||
enableDamping?: boolean;
|
||||
/** 阻尼因子 */
|
||||
dampingFactor?: number;
|
||||
/** 最小视场角 */
|
||||
minFov?: number;
|
||||
/** 最大视场角 */
|
||||
maxFov?: number;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 全景操作
|
||||
|
||||
### loadPanorama()
|
||||
|
||||
```typescript
|
||||
public async loadPanorama(url: string, options?: PanoramaLoadOptions): Promise<void>
|
||||
```
|
||||
|
||||
**功能**: 加载全景图
|
||||
|
||||
**参数**:
|
||||
- `url`: string — 全景图片 URL（等距柱状投影格式）
|
||||
- `options`: PanoramaLoadOptions — 加载选项（可选）
|
||||
|
||||
**返回值**: Promise\<void\>
|
||||
|
||||
```typescript
|
||||
interface PanoramaLoadOptions {
|
||||
/** 加载超时时间（毫秒） */
|
||||
timeout?: number;
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```typescript
|
||||
await engine720.loadPanorama('https://example.com/panorama.png');
|
||||
```
|
||||
|
||||
### preloadPanoramas()
|
||||
|
||||
```typescript
|
||||
public async preloadPanoramas(urls: string[]): Promise<void>
|
||||
```
|
||||
|
||||
**功能**: 预加载多个全景图（用于场景切换时减少加载等待）
|
||||
|
||||
**参数**:
|
||||
- `urls`: string[] — 全景图片 URL 数组
|
||||
|
||||
**示例**:
|
||||
|
||||
```typescript
|
||||
await engine720.preloadPanoramas([
|
||||
'https://example.com/room1.png',
|
||||
'https://example.com/room2.png',
|
||||
'https://example.com/room3.png'
|
||||
]);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 视角控制
|
||||
|
||||
### setFov()
|
||||
|
||||
```typescript
|
||||
public setFov(fov: number): void
|
||||
```
|
||||
|
||||
**功能**: 设置视场角（Field of View）
|
||||
|
||||
**参数**:
|
||||
- `fov`: number — 视场角度数
|
||||
|
||||
### getFov()
|
||||
|
||||
```typescript
|
||||
public getFov(): number
|
||||
```
|
||||
|
||||
**功能**: 获取当前视场角
|
||||
|
||||
**返回值**: number — 当前视场角，默认 75
|
||||
|
||||
### lookAt()
|
||||
|
||||
```typescript
|
||||
public lookAt(phi: number, theta: number, animated?: boolean): void
|
||||
```
|
||||
|
||||
**功能**: 设置相机朝向（球面坐标）
|
||||
|
||||
**参数**:
|
||||
- `phi`: number — 水平角度
|
||||
- `theta`: number — 垂直角度
|
||||
- `animated`: boolean — 是否动画过渡（可选）
|
||||
|
||||
**示例**:
|
||||
|
||||
```typescript
|
||||
// 看向指定方向
|
||||
engine720.lookAt(Math.PI / 4, Math.PI / 6, true);
|
||||
```
|
||||
|
||||
### resetView()
|
||||
|
||||
```typescript
|
||||
public resetView(): void
|
||||
```
|
||||
|
||||
**功能**: 重置视角到初始状态
|
||||
|
||||
---
|
||||
|
||||
## 主题
|
||||
|
||||
### setTheme()
|
||||
|
||||
```typescript
|
||||
public setTheme(theme: 'dark' | 'light'): void
|
||||
```
|
||||
|
||||
**功能**: 切换主题
|
||||
|
||||
**参数**:
|
||||
- `theme`: 'dark' | 'light'
|
||||
|
||||
---
|
||||
|
||||
## 事件
|
||||
|
||||
### on()
|
||||
|
||||
```typescript
|
||||
public on<K extends keyof EngineEvents>(
|
||||
event: K,
|
||||
listener: (payload: EngineEvents[K]) => void
|
||||
): () => void
|
||||
```
|
||||
|
||||
**功能**: 订阅事件
|
||||
|
||||
**返回值**: 取消订阅函数
|
||||
|
||||
**示例**:
|
||||
|
||||
```typescript
|
||||
const unsub = engine720.on('engine:model-loaded', (payload) => {
|
||||
console.log('全景图加载完成');
|
||||
});
|
||||
|
||||
// 取消订阅
|
||||
unsub();
|
||||
```
|
||||
|
||||
### off()
|
||||
|
||||
```typescript
|
||||
public off<K extends keyof EngineEvents>(
|
||||
event: K,
|
||||
listener: (payload: EngineEvents[K]) => void
|
||||
): void
|
||||
```
|
||||
|
||||
**功能**: 取消事件订阅
|
||||
|
||||
### onRawEvent()
|
||||
|
||||
```typescript
|
||||
public onRawEvent(event: string, handler: (...args: any[]) => void): void
|
||||
```
|
||||
|
||||
**功能**: 订阅底层 720 引擎的原始事件
|
||||
|
||||
### offRawEvent()
|
||||
|
||||
```typescript
|
||||
public offRawEvent(event: string, handler: (...args: any[]) => void): void
|
||||
```
|
||||
|
||||
**功能**: 取消订阅底层 720 引擎的原始事件
|
||||
|
||||
---
|
||||
|
||||
## 生命周期
|
||||
|
||||
### destroy()
|
||||
|
||||
```typescript
|
||||
public destroy(): void
|
||||
```
|
||||
|
||||
**功能**: 销毁引擎，释放所有资源
|
||||
|
||||
- 销毁底层 Engine720 组件
|
||||
- 重置 ManagerRegistry
|
||||
- 调用后实例不可再使用
|
||||
|
||||
**重要**: 切换引擎类型或页面卸载时务必调用。
|
||||
|
||||
---
|
||||
|
||||
## 内部架构
|
||||
|
||||
```text
|
||||
BimEngine720 (用户 API)
|
||||
├─ ManagerRegistry (仅事件总线，不注册 Manager)
|
||||
└─ Engine720 组件 (IBimComponent)
|
||||
└─ createEngine720() (iflow-engine-base)
|
||||
```
|
||||
|
||||
与 `BimEngine`（3D）的关键区别：
|
||||
|
||||
| | BimEngine (3D) | BimEngine720 (720°) |
|
||||
|---|---|---|
|
||||
| Manager 层 | 15 个 Manager | 无（跳过 Manager 层） |
|
||||
| UI 组件 | toolbar、dialog、menu 等 | 无 |
|
||||
| 初始化 | 需要调用 `engine.initialize()` | 构造时自动初始化 |
|
||||
| ManagerRegistry | 完整注册所有 Manager | 仅用于事件发射 |
|
||||
|
||||
---
|
||||
|
||||
## 相关类型
|
||||
|
||||
```typescript
|
||||
/** 全景标注信息（预留扩展） */
|
||||
interface PanoramaAnnotation {
|
||||
/** 标注 ID */
|
||||
id: string;
|
||||
/** 标注位置（球面坐标 phi） */
|
||||
phi?: number;
|
||||
/** 标注位置（球面坐标 theta） */
|
||||
theta?: number;
|
||||
/** 标注文本 */
|
||||
text?: string;
|
||||
/** 自定义数据 */
|
||||
data?: any;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: 1.0.0 | **更新日期**: 2026-03-10
|
||||
@@ -14,7 +14,7 @@
|
||||
```
|
||||
src/core/
|
||||
├── event-emitter.ts # 事件发射器
|
||||
├── manager-registry.ts # Manager 注册表（单例）
|
||||
├── manager-registry.ts # Manager 注册表（实例化）
|
||||
├── base-manager.ts # Manager 抽象基类
|
||||
└── base-dialog-manager.ts # 对话框 Manager 基类
|
||||
```
|
||||
@@ -22,7 +22,7 @@ src/core/
|
||||
| 文件 | 行数 | 职责 | 导出 |
|
||||
|------|------|------|------|
|
||||
| `event-emitter.ts` | 70 | 发布/订阅事件系统 | `EventEmitter` |
|
||||
| `manager-registry.ts` | 127 | 全局单例注册表 | `ManagerRegistry` |
|
||||
| `manager-registry.ts` | 127 | 实例级 Manager 注册表 | `ManagerRegistry` |
|
||||
| `base-manager.ts` | 57 | Manager 基类 | `BaseManager` |
|
||||
| `base-dialog-manager.ts` | 145 | 对话框 Manager 基类 | `BaseDialogManager` |
|
||||
|
||||
@@ -33,7 +33,7 @@ src/core/
|
||||
```
|
||||
EventEmitter
|
||||
↑ (组合)
|
||||
ManagerRegistry (单例)
|
||||
ManagerRegistry (实例)
|
||||
↑ (访问)
|
||||
BaseManager (抽象类)
|
||||
↑ (继承)
|
||||
@@ -46,7 +46,7 @@ BaseDialogManager (抽象类)
|
||||
|
||||
| 模式 | 应用 | 说明 |
|
||||
|------|------|------|
|
||||
| 单例模式 | ManagerRegistry | 全局唯一实例 |
|
||||
| 实例模式 | ManagerRegistry | 每个引擎实例独立注册表 |
|
||||
| 发布/订阅 | EventEmitter | 解耦事件通信 |
|
||||
| 模板方法 | BaseDialogManager | 定义对话框生命周期 |
|
||||
|
||||
@@ -99,17 +99,14 @@ unsubscribe();
|
||||
|
||||
### 概述
|
||||
|
||||
全局单例注册表，集中管理所有 Manager 实例，提供跨 Manager 通信。
|
||||
实例级注册表，集中管理单个引擎实例下的 Manager 与事件总线，支持多实例隔离。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class ManagerRegistry {
|
||||
// 获取单例
|
||||
static getInstance(): ManagerRegistry;
|
||||
|
||||
// 重置单例（用于测试）
|
||||
static reset(): void;
|
||||
// 创建实例
|
||||
constructor();
|
||||
|
||||
// 容器元素
|
||||
container: HTMLElement | null;
|
||||
@@ -125,25 +122,30 @@ class ManagerRegistry {
|
||||
componentDetail: ComponentDetailManager | null;
|
||||
measure: MeasureDialogManager | null;
|
||||
walkControl: WalkControlManager | null;
|
||||
map: MapDialogManager | null;
|
||||
sectionPlane: SectionPlaneDialogManager | null;
|
||||
sectionAxis: SectionAxisDialogManager | null;
|
||||
sectionBox: SectionBoxDialogManager | null;
|
||||
walkPath: WalkPathDialogManager | null;
|
||||
walkPlanView: WalkPlanViewDialogManager | null;
|
||||
engineInfo: EngineInfoDialogManager | null;
|
||||
aiChat: AiChatManager | null;
|
||||
setting: SettingDialogManager | null;
|
||||
|
||||
// 事件方法
|
||||
emit<K extends keyof EngineEvents>(event: K, payload: EngineEvents[K]): void;
|
||||
on<K extends keyof EngineEvents>(event: K, listener: (payload: EngineEvents[K]) => void): () => void;
|
||||
off<K extends keyof EngineEvents>(event: K, listener: (payload: EngineEvents[K]) => void): void;
|
||||
clearEvents(): void;
|
||||
reset(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
const registry = ManagerRegistry.getInstance();
|
||||
const registry = new ManagerRegistry();
|
||||
|
||||
// 访问 Manager
|
||||
// 由引擎入口在初始化时写入各个 Manager 实例
|
||||
registry.toolbar?.show();
|
||||
registry.measure?.switchMode('distance');
|
||||
|
||||
|
||||
@@ -5,8 +5,8 @@
|
||||
| 模块 | 路径 | 职责 | 文档 |
|
||||
|------|------|------|------|
|
||||
| **core** | `src/core/` | 核心基础设施：事件系统、管理器基类、注册表 | [核心模块.md](核心模块.md) |
|
||||
| **managers** | `src/managers/` | 15 个管理器，处理业务逻辑和组件协调 | [管理器模块.md](管理器模块.md) |
|
||||
| **components** | `src/components/` | 20+ 个 UI 组件 | [组件模块.md](组件模块.md) |
|
||||
| **managers** | `src/managers/` | 15 个管理器，处理业务逻辑和组件协调（仅 3D） | [管理器模块.md](管理器模块.md) |
|
||||
| **components** | `src/components/` | 3 个引擎组件 + 20+ UI 组件 | [组件模块.md](组件模块.md) |
|
||||
| **services** | `src/services/` | 全局服务：国际化、主题管理 | [服务模块.md](服务模块.md) |
|
||||
|
||||
## Core 模块
|
||||
@@ -16,7 +16,7 @@
|
||||
| 类 | 文件 | 职责 |
|
||||
|-----|------|------|
|
||||
| EventEmitter | `event-emitter.ts` | 事件发布/订阅系统 |
|
||||
| ManagerRegistry | `manager-registry.ts` | 全局单例注册表 |
|
||||
| ManagerRegistry | `manager-registry.ts` | 实例级注册表，隔离每个引擎实例的 Manager 与事件 |
|
||||
| BaseManager | `base-manager.ts` | Manager 抽象基类 |
|
||||
| BaseDialogManager | `base-dialog-manager.ts` | 对话框 Manager 基类 |
|
||||
|
||||
@@ -57,11 +57,18 @@
|
||||
|
||||
纯 UI 组件，不包含业务逻辑。
|
||||
|
||||
### 核心组件
|
||||
### 引擎组件
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| Engine | 3D 视口容器（包装 iflow-engine-base） |
|
||||
| Engine2d | 2D 图纸视口（包装 createEngine2d） |
|
||||
| Engine720 | 720° 全景视口（包装 createEngine720） |
|
||||
|
||||
### 核心 UI 组件
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| Engine | 3D 视口容器 |
|
||||
| BimDialog | 通用对话框 |
|
||||
| BimTree | 树形控件 |
|
||||
| BimMenu | 菜单组件 |
|
||||
@@ -106,7 +113,7 @@
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| `types/component.ts` | 组件接口 IBimComponent |
|
||||
| `types/events.ts` | 事件类型 EngineEvents |
|
||||
| `types/events.ts` | 事件类型 EngineEvents（含 3D/2D/720 事件） |
|
||||
| `types/measure.ts` | 测量类型定义 |
|
||||
| `locales/types.ts` | 国际化类型 |
|
||||
| `themes/types.ts` | 主题配置类型 |
|
||||
@@ -119,4 +126,4 @@
|
||||
|
||||
---
|
||||
|
||||
**文档生成时间**: 2026-01-23
|
||||
**文档更新时间**: 2026-03-10
|
||||
|
||||
@@ -5,15 +5,17 @@
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **模块名** | components |
|
||||
| **职责** | 提供 BIM 3D 引擎 SDK 的所有 UI 组件 |
|
||||
| **公开 API** | 20+ 个组件类 |
|
||||
| **职责** | 提供 BIM SDK 的所有引擎组件（3D / 2D / 720）和 UI 组件 |
|
||||
| **公开 API** | 3 个引擎组件 + 20+ UI 组件 |
|
||||
| **状态** | ✅ 稳定 |
|
||||
|
||||
## 代码地图
|
||||
|
||||
```
|
||||
src/components/
|
||||
├── engine/ # 3D 引擎组件
|
||||
├── engine/ # 3D 引擎组件 (包装 iflow-engine-base)
|
||||
├── engine-2d/ # 2D 图纸引擎组件 (包装 createEngine2d)
|
||||
├── engine-720/ # 720° 全景引擎组件 (包装 createEngine720)
|
||||
├── dialog/ # 通用弹窗组件
|
||||
├── tree/ # 树形控件组件
|
||||
├── menu/ # 菜单组件
|
||||
@@ -30,7 +32,6 @@ src/components/
|
||||
├── walk-plan-view-panel/ # 漫游平面图面板
|
||||
├── right-key/ # 右键菜单组件
|
||||
└── map-panel/ # 地图面板组件
|
||||
```
|
||||
|
||||
## 组件接口
|
||||
|
||||
@@ -52,7 +53,7 @@ interface IBimComponent {
|
||||
|
||||
### 概述
|
||||
|
||||
包装第三方 3D 引擎 SDK，提供模型加载、视角控制、测量功能。
|
||||
包装第三方 3D 引擎 SDK，提供模型加载、视角控制、测量功能。仅由 `BimEngine` 通过 `EngineManager` 使用。
|
||||
|
||||
### 配置
|
||||
|
||||
@@ -69,33 +70,135 @@ interface EngineOptions {
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class Engine {
|
||||
class Engine implements IBimComponent {
|
||||
init(): void;
|
||||
loadModel(url: string, options?: ModelLoadOptions): void;
|
||||
CameraGoHome(): void;
|
||||
getEngine(): any;
|
||||
activateMeasure(mode: MeasureMode): void;
|
||||
deactivateMeasure(): void;
|
||||
onRawEvent(event: string, handler: Function): void;
|
||||
offRawEvent(event: string, handler: Function): void;
|
||||
setTheme(theme: ThemeConfig): void;
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 测量模式
|
||||
---
|
||||
|
||||
| 模式 | 说明 |
|
||||
|------|------|
|
||||
| `distance` | 距离测量 |
|
||||
| `minDistance` | 最小距离 |
|
||||
| `angle` | 角度测量 |
|
||||
| `elevation` | 标高测量 |
|
||||
| `volume` | 体积测量 |
|
||||
| `laserDistance` | 激光测距 |
|
||||
| `slope` | 坡度测量 |
|
||||
| `spaceVolume` | 空间体积 |
|
||||
## Engine2d（2D 图纸引擎组件）
|
||||
|
||||
### 概述
|
||||
|
||||
包装 `createEngine2d()`，提供 2D CAD/DWG 图纸加载与查看。由 `BimEngine2d` 直接使用，跳过 Manager 层。
|
||||
|
||||
### 配置
|
||||
|
||||
```typescript
|
||||
interface Engine2dOptions {
|
||||
container: HTMLElement;
|
||||
backgroundColor?: number;
|
||||
gridEnabled?: boolean;
|
||||
axesEnabled?: boolean;
|
||||
selectionColor?: number;
|
||||
highlightColor?: number;
|
||||
enablePerformanceMonitoring?: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class Engine2d implements IBimComponent {
|
||||
init(): void;
|
||||
loadDrawing(url: string, options?: DrawingLoadOptions): Promise<void>;
|
||||
getLayers(): Drawing2dLayer[];
|
||||
setLayerVisible(name: string, visible: boolean): void;
|
||||
resetView(): void;
|
||||
fitToView(): void;
|
||||
setZoom(zoom: number): void;
|
||||
getZoom(): number;
|
||||
onRawEvent(event: string, handler: Function): void;
|
||||
offRawEvent(event: string, handler: Function): void;
|
||||
setTheme(theme: ThemeConfig): void;
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 相关类型
|
||||
|
||||
```typescript
|
||||
interface DrawingLoadOptions {
|
||||
chunkSize?: number;
|
||||
enableChunkedLoading?: boolean;
|
||||
enableValidation?: boolean;
|
||||
}
|
||||
|
||||
interface Drawing2dLayer {
|
||||
name: string;
|
||||
visible: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Engine720（720° 全景引擎组件）
|
||||
|
||||
### 概述
|
||||
|
||||
包装 `createEngine720()`，提供 720° 全景图加载与查看。由 `BimEngine720` 直接使用，跳过 Manager 层。
|
||||
|
||||
### 配置
|
||||
|
||||
```typescript
|
||||
interface Engine720Options {
|
||||
container: HTMLElement;
|
||||
fov?: number; // 默认 75
|
||||
enableZoom?: boolean; // 默认 true
|
||||
enableRotate?: boolean; // 默认 true
|
||||
sphereRadius?: number; // 默认 500
|
||||
rotateSpeed?: number;
|
||||
zoomSpeed?: number;
|
||||
enableDamping?: boolean;
|
||||
dampingFactor?: number;
|
||||
minFov?: number;
|
||||
maxFov?: number;
|
||||
}
|
||||
```
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class Engine720 implements IBimComponent {
|
||||
init(): void;
|
||||
loadPanorama(url: string, options?: PanoramaLoadOptions): Promise<void>;
|
||||
preloadPanoramas(urls: string[]): Promise<void>;
|
||||
setFov(fov: number): void;
|
||||
getFov(): number;
|
||||
lookAt(phi: number, theta: number, animated?: boolean): void;
|
||||
resetView(): void;
|
||||
onRawEvent(event: string, handler: Function): void;
|
||||
offRawEvent(event: string, handler: Function): void;
|
||||
setTheme(theme: ThemeConfig): void;
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 相关类型
|
||||
|
||||
```typescript
|
||||
interface PanoramaLoadOptions {
|
||||
timeout?: number;
|
||||
}
|
||||
|
||||
interface PanoramaAnnotation {
|
||||
id: string;
|
||||
phi?: number;
|
||||
theta?: number;
|
||||
text?: string;
|
||||
data?: any;
|
||||
}
|
||||
```
|
||||
|
||||
## BimDialog（通用弹窗组件）
|
||||
|
||||
### 概述
|
||||
@@ -602,4 +705,4 @@ interface WalkControlState {
|
||||
|
||||
---
|
||||
|
||||
**文档生成时间**: 2026-01-23
|
||||
**文档更新时间**: 2026-03-10
|
||||
|
||||
807
docs/快速开始.md
807
docs/快速开始.md
@@ -20,83 +20,129 @@ yarn add iflow-engine
|
||||
pnpm add iflow-engine
|
||||
```
|
||||
|
||||
## 基础使用
|
||||
## 引擎概览
|
||||
|
||||
### 1. 创建 HTML 容器
|
||||
SDK 提供三个独立引擎类，按需引入，互不依赖：
|
||||
|
||||
```html
|
||||
<div id="bim-container" style="width: 100%; height: 100vh;"></div>
|
||||
| 类名 | 用途 | 定位 |
|
||||
|---|---|---|
|
||||
| `BimEngine` | 3D BIM 模型可视化 | 完整功能（工具栏、测量、剖切、漫游等 UI 组件） |
|
||||
| `BimEngine2d` | 2D CAD/DWG 图纸查看 | 轻量级，无 UI 管理器 |
|
||||
| `BimEngine720` | 720° 全景图查看 | 轻量级，无 UI 管理器 |
|
||||
|
||||
```typescript
|
||||
// ESM 按需导入
|
||||
import { BimEngine } from 'iflow-engine'; // 3D
|
||||
import { BimEngine2d } from 'iflow-engine'; // 2D
|
||||
import { BimEngine720 } from 'iflow-engine'; // 720°
|
||||
|
||||
// 也可以一次导入全部
|
||||
import { BimEngine, BimEngine2d, BimEngine720 } from 'iflow-engine';
|
||||
```
|
||||
|
||||
### 2. 初始化引擎
|
||||
```html
|
||||
<!-- UMD 方式（原生 HTML） -->
|
||||
<script src="./lib/iflow-engine.umd.js"></script>
|
||||
<script>
|
||||
const { BimEngine, BimEngine2d, BimEngine720 } = IflowEngine;
|
||||
</script>
|
||||
```
|
||||
|
||||
> **注意**：三个引擎类共用同一个容器时，需先销毁当前实例再创建新实例。详见 [多引擎切换](#多引擎切换)。
|
||||
|
||||
---
|
||||
|
||||
## 一、3D 引擎（BimEngine）
|
||||
|
||||
完整的 BIM 3D 可视化引擎，包含工具栏、测量、剖切、漫游等全部 UI 功能。
|
||||
|
||||
### 基本用法
|
||||
|
||||
```typescript
|
||||
import { BimEngine } from 'iflow-engine';
|
||||
|
||||
// 创建引擎实例
|
||||
const engine = new BimEngine('bim-container', {
|
||||
locale: 'zh-CN', // 语言：'zh-CN' | 'en-US'
|
||||
theme: 'light' // 主题：'light' | 'dark'
|
||||
const engine = new BimEngine('container', {
|
||||
locale: 'zh-CN', // 'zh-CN' | 'en-US'
|
||||
theme: 'dark' // 'dark' | 'light'
|
||||
});
|
||||
```
|
||||
|
||||
### 3. 加载模型
|
||||
|
||||
```typescript
|
||||
// 初始化 3D 引擎
|
||||
engine.engine?.initialize();
|
||||
// 初始化 3D 渲染引擎
|
||||
engine.engine?.initialize({
|
||||
backgroundColor: 0x333333,
|
||||
showViewCube: true
|
||||
});
|
||||
|
||||
// 加载模型
|
||||
engine.engine?.loadModel('https://example.com/model.gltf', {
|
||||
autoFit: true // 自动适配视角
|
||||
engine.engine?.loadModel(['https://example.com/model/'], {
|
||||
position: [0, 0, 0],
|
||||
rotation: [0, 0, 0],
|
||||
scale: [1, 1, 1]
|
||||
});
|
||||
```
|
||||
|
||||
## 完整示例
|
||||
### 构造参数
|
||||
|
||||
### Vue 3
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `container` | `HTMLElement \| string` | ✅ | DOM 元素或元素 ID |
|
||||
| `options.locale` | `'zh-CN' \| 'en-US'` | | 界面语言，默认 `'zh-CN'` |
|
||||
| `options.theme` | `'dark' \| 'light'` | | 主题，默认 `'dark'` |
|
||||
|
||||
### 管理器
|
||||
|
||||
BimEngine 构造时自动初始化以下管理器：
|
||||
|
||||
```typescript
|
||||
engine.engine // EngineManager - 3D 引擎（加载模型、控制渲染）
|
||||
engine.toolbar // ToolbarManager - 底部工具栏
|
||||
engine.buttonGroup // ButtonGroupManager - 按钮组
|
||||
engine.dialog // DialogManager - 弹窗管理
|
||||
engine.rightKey // RightKeyManager - 右键菜单
|
||||
engine.constructTreeBtn // ConstructTreeManagerBtn - 构件树
|
||||
engine.measure // MeasureDialogManager - 测量工具
|
||||
engine.sectionPlane // SectionPlaneDialogManager - 拾取面剖切
|
||||
engine.sectionAxis // SectionAxisDialogManager - 轴向剖切
|
||||
engine.sectionBox // SectionBoxDialogManager - 剖切盒
|
||||
engine.walkControl // WalkControlManager - 漫游控制
|
||||
engine.componentDetail // ComponentDetailManager - 构件详情
|
||||
engine.aiChat // AiChatManager - AI 对话
|
||||
engine.setting // SettingDialogManager - 设置
|
||||
```
|
||||
|
||||
### Vue 3 示例
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<div ref="containerRef" class="bim-container"></div>
|
||||
<div ref="containerRef" style="width: 100vw; height: 100vh;" />
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import { ref, onMounted, onUnmounted } from 'vue';
|
||||
import { BimEngine } from 'iflow-engine';
|
||||
|
||||
const containerRef = ref<HTMLElement | null>(null);
|
||||
const containerRef = ref<HTMLElement>();
|
||||
let engine: BimEngine | null = null;
|
||||
|
||||
onMounted(() => {
|
||||
if (containerRef.value) {
|
||||
engine = new BimEngine(containerRef.value, {
|
||||
locale: 'zh-CN',
|
||||
theme: 'light'
|
||||
});
|
||||
if (!containerRef.value) return;
|
||||
|
||||
// 初始化 3D 引擎
|
||||
engine.engine?.initialize();
|
||||
engine = new BimEngine(containerRef.value, {
|
||||
locale: 'zh-CN',
|
||||
theme: 'dark'
|
||||
});
|
||||
|
||||
// 加载模型
|
||||
engine.engine?.loadModel('/models/building.gltf');
|
||||
}
|
||||
engine.engine?.initialize({ backgroundColor: 0x333333 });
|
||||
engine.engine?.loadModel(['https://example.com/model/']);
|
||||
});
|
||||
|
||||
onUnmounted(() => {
|
||||
engine?.destroy();
|
||||
engine = null;
|
||||
});
|
||||
</script>
|
||||
|
||||
<style scoped>
|
||||
.bim-container {
|
||||
width: 100%;
|
||||
height: 100vh;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
### React
|
||||
### React 示例
|
||||
|
||||
```tsx
|
||||
import { useRef, useEffect } from 'react';
|
||||
@@ -104,285 +150,514 @@ import { BimEngine } from 'iflow-engine';
|
||||
|
||||
export function BimViewer() {
|
||||
const containerRef = useRef<HTMLDivElement>(null);
|
||||
const engineRef = useRef<BimEngine | null>(null);
|
||||
|
||||
useEffect(() => {
|
||||
if (containerRef.current && !engineRef.current) {
|
||||
engineRef.current = new BimEngine(containerRef.current, {
|
||||
locale: 'zh-CN',
|
||||
theme: 'light'
|
||||
});
|
||||
if (!containerRef.current) return;
|
||||
|
||||
// 初始化 3D 引擎
|
||||
engineRef.current.engine?.initialize();
|
||||
const engine = new BimEngine(containerRef.current, {
|
||||
locale: 'zh-CN',
|
||||
theme: 'dark'
|
||||
});
|
||||
|
||||
// 加载模型
|
||||
engineRef.current.engine?.loadModel('/models/building.gltf');
|
||||
}
|
||||
engine.engine?.initialize({ backgroundColor: 0x333333 });
|
||||
engine.engine?.loadModel(['https://example.com/model/']);
|
||||
|
||||
return () => {
|
||||
engineRef.current?.destroy();
|
||||
engineRef.current = null;
|
||||
};
|
||||
return () => engine.destroy();
|
||||
}, []);
|
||||
|
||||
return <div ref={containerRef} style={{ width: '100vw', height: '100vh' }} />;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、2D 图纸引擎（BimEngine2d）
|
||||
|
||||
轻量级 2D CAD/DWG 图纸查看引擎，无 UI 管理器，构造时自动初始化。
|
||||
|
||||
### 基本用法
|
||||
|
||||
```typescript
|
||||
import { BimEngine2d } from 'iflow-engine';
|
||||
|
||||
const engine2d = new BimEngine2d('container', {
|
||||
locale: 'zh-CN',
|
||||
theme: 'dark',
|
||||
backgroundColor: 0xf0f0f0,
|
||||
gridEnabled: true,
|
||||
axesEnabled: true
|
||||
});
|
||||
|
||||
// 加载图纸
|
||||
await engine2d.loadDrawing('https://example.com/drawing-id');
|
||||
|
||||
// 销毁
|
||||
engine2d.destroy();
|
||||
```
|
||||
|
||||
### 构造参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `container` | `HTMLElement \| string` | ✅ | DOM 元素或元素 ID |
|
||||
| `options.locale` | `'zh-CN' \| 'en-US'` | | 界面语言 |
|
||||
| `options.theme` | `'dark' \| 'light'` | | 主题 |
|
||||
| `options.backgroundColor` | `number` | | 背景色，如 `0xffffff` |
|
||||
| `options.gridEnabled` | `boolean` | | 是否显示网格 |
|
||||
| `options.axesEnabled` | `boolean` | | 是否显示坐标轴 |
|
||||
| `options.selectionColor` | `number` | | 选中构件颜色 |
|
||||
| `options.highlightColor` | `number` | | 高亮构件颜色 |
|
||||
| `options.enablePerformanceMonitoring` | `boolean` | | 是否启用性能监控 |
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
// 图纸操作
|
||||
await engine2d.loadDrawing(url, options?) // 加载图纸
|
||||
engine2d.getLayers() // 获取所有图层 → Drawing2dLayer[]
|
||||
engine2d.setLayerVisible(name, visible) // 设置图层可见性
|
||||
|
||||
// 视图控制
|
||||
engine2d.resetView() // 重置视图
|
||||
engine2d.fitToView() // 适应全部内容
|
||||
engine2d.setZoom(zoom) // 设置缩放级别
|
||||
engine2d.getZoom() // 获取当前缩放级别
|
||||
|
||||
// 主题
|
||||
engine2d.setTheme('dark' | 'light')
|
||||
|
||||
// 事件
|
||||
const unsub = engine2d.on('event-name', (payload) => { ... })
|
||||
unsub() // 取消订阅
|
||||
engine2d.onRawEvent(event, handler) // 底层引擎事件
|
||||
engine2d.offRawEvent(event, handler)
|
||||
|
||||
// 生命周期
|
||||
engine2d.destroy() // 销毁引擎
|
||||
```
|
||||
|
||||
### Vue 3 示例
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<div ref="containerRef" style="width: 100%; height: 100vh;" />
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import { ref, onMounted, onUnmounted } from 'vue';
|
||||
import { BimEngine2d } from 'iflow-engine';
|
||||
|
||||
const containerRef = ref<HTMLElement>();
|
||||
let engine2d: BimEngine2d | null = null;
|
||||
|
||||
onMounted(async () => {
|
||||
if (!containerRef.value) return;
|
||||
|
||||
engine2d = new BimEngine2d(containerRef.value, {
|
||||
theme: 'light',
|
||||
gridEnabled: true
|
||||
});
|
||||
|
||||
await engine2d.loadDrawing('https://example.com/drawing-id');
|
||||
});
|
||||
|
||||
onUnmounted(() => {
|
||||
engine2d?.destroy();
|
||||
engine2d = null;
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
### React 示例
|
||||
|
||||
```tsx
|
||||
import { useRef, useEffect } from 'react';
|
||||
import { BimEngine2d } from 'iflow-engine';
|
||||
|
||||
export function DrawingViewer() {
|
||||
const containerRef = useRef<HTMLDivElement>(null);
|
||||
|
||||
useEffect(() => {
|
||||
if (!containerRef.current) return;
|
||||
|
||||
const engine2d = new BimEngine2d(containerRef.current, {
|
||||
theme: 'light',
|
||||
gridEnabled: true
|
||||
});
|
||||
|
||||
engine2d.loadDrawing('https://example.com/drawing-id');
|
||||
|
||||
return () => engine2d.destroy();
|
||||
}, []);
|
||||
|
||||
return <div ref={containerRef} style={{ width: '100%', height: '100vh' }} />;
|
||||
}
|
||||
```
|
||||
|
||||
### 原生 HTML
|
||||
---
|
||||
|
||||
## 三、720° 全景引擎（BimEngine720）
|
||||
|
||||
轻量级 720° 全景图查看引擎，支持鼠标/触摸旋转和缩放，构造时自动初始化。
|
||||
|
||||
### 基本用法
|
||||
|
||||
```typescript
|
||||
import { BimEngine720 } from 'iflow-engine';
|
||||
|
||||
const engine720 = new BimEngine720('container', {
|
||||
fov: 75,
|
||||
enableZoom: true,
|
||||
enableRotate: true,
|
||||
sphereRadius: 500
|
||||
});
|
||||
|
||||
// 加载全景图
|
||||
await engine720.loadPanorama('https://example.com/panorama.png');
|
||||
|
||||
// 销毁
|
||||
engine720.destroy();
|
||||
```
|
||||
|
||||
### 构造参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `container` | `HTMLElement \| string` | ✅ | DOM 元素或元素 ID |
|
||||
| `options.locale` | `'zh-CN' \| 'en-US'` | | 界面语言 |
|
||||
| `options.theme` | `'dark' \| 'light'` | | 主题 |
|
||||
| `options.fov` | `number` | | 视场角，默认 `75` |
|
||||
| `options.enableZoom` | `boolean` | | 是否启用缩放，默认 `true` |
|
||||
| `options.enableRotate` | `boolean` | | 是否启用旋转，默认 `true` |
|
||||
| `options.sphereRadius` | `number` | | 球体半径，默认 `500` |
|
||||
| `options.rotateSpeed` | `number` | | 旋转速度 |
|
||||
| `options.zoomSpeed` | `number` | | 缩放速度 |
|
||||
| `options.enableDamping` | `boolean` | | 是否启用阻尼（惯性效果） |
|
||||
| `options.dampingFactor` | `number` | | 阻尼因子 |
|
||||
| `options.minFov` | `number` | | 最小视场角 |
|
||||
| `options.maxFov` | `number` | | 最大视场角 |
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
// 全景操作
|
||||
await engine720.loadPanorama(url, options?) // 加载全景图
|
||||
await engine720.preloadPanoramas(urls) // 预加载多个全景图
|
||||
|
||||
// 视角控制
|
||||
engine720.setFov(fov) // 设置视场角
|
||||
engine720.getFov() // 获取当前视场角
|
||||
engine720.lookAt(phi, theta, animated?) // 设置相机朝向
|
||||
engine720.resetView() // 重置视图
|
||||
|
||||
// 主题
|
||||
engine720.setTheme('dark' | 'light')
|
||||
|
||||
// 事件
|
||||
const unsub = engine720.on('event-name', (payload) => { ... })
|
||||
unsub() // 取消订阅
|
||||
engine720.onRawEvent(event, handler) // 底层引擎事件
|
||||
engine720.offRawEvent(event, handler)
|
||||
|
||||
// 生命周期
|
||||
engine720.destroy() // 销毁引擎
|
||||
```
|
||||
|
||||
### Vue 3 示例
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<div ref="containerRef" style="width: 100%; height: 100vh;" />
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import { ref, onMounted, onUnmounted } from 'vue';
|
||||
import { BimEngine720 } from 'iflow-engine';
|
||||
|
||||
const containerRef = ref<HTMLElement>();
|
||||
let engine720: BimEngine720 | null = null;
|
||||
|
||||
onMounted(async () => {
|
||||
if (!containerRef.value) return;
|
||||
|
||||
engine720 = new BimEngine720(containerRef.value, {
|
||||
fov: 75,
|
||||
enableZoom: true,
|
||||
enableRotate: true,
|
||||
sphereRadius: 500
|
||||
});
|
||||
|
||||
await engine720.loadPanorama('https://example.com/panorama.png');
|
||||
});
|
||||
|
||||
onUnmounted(() => {
|
||||
engine720?.destroy();
|
||||
engine720 = null;
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
### React 示例
|
||||
|
||||
```tsx
|
||||
import { useRef, useEffect } from 'react';
|
||||
import { BimEngine720 } from 'iflow-engine';
|
||||
|
||||
export function PanoramaViewer() {
|
||||
const containerRef = useRef<HTMLDivElement>(null);
|
||||
|
||||
useEffect(() => {
|
||||
if (!containerRef.current) return;
|
||||
|
||||
const engine720 = new BimEngine720(containerRef.current, {
|
||||
fov: 75,
|
||||
enableZoom: true,
|
||||
enableRotate: true,
|
||||
sphereRadius: 500
|
||||
});
|
||||
|
||||
engine720.loadPanorama('https://example.com/panorama.png');
|
||||
|
||||
return () => engine720.destroy();
|
||||
}, []);
|
||||
|
||||
return <div ref={containerRef} style={{ width: '100%', height: '100vh' }} />;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 多引擎切换
|
||||
|
||||
三个引擎类可以共用同一个容器，但同一时刻只能有一个实例。切换时需先销毁当前实例：
|
||||
|
||||
```typescript
|
||||
import { BimEngine, BimEngine2d, BimEngine720 } from 'iflow-engine';
|
||||
|
||||
let current: BimEngine | BimEngine2d | BimEngine720 | null = null;
|
||||
|
||||
function destroyCurrent() {
|
||||
current?.destroy();
|
||||
current = null;
|
||||
}
|
||||
|
||||
// 切换到 3D
|
||||
function switchTo3D() {
|
||||
destroyCurrent();
|
||||
const engine = new BimEngine('container', { theme: 'dark' });
|
||||
engine.engine?.initialize({ backgroundColor: 0x333333 });
|
||||
engine.engine?.loadModel(['https://example.com/model/']);
|
||||
current = engine;
|
||||
}
|
||||
|
||||
// 切换到 2D
|
||||
function switchTo2D() {
|
||||
destroyCurrent();
|
||||
const engine2d = new BimEngine2d('container', { theme: 'dark' });
|
||||
engine2d.loadDrawing('https://example.com/drawing-id');
|
||||
current = engine2d;
|
||||
}
|
||||
|
||||
// 切换到 720°
|
||||
function switchTo720() {
|
||||
destroyCurrent();
|
||||
const engine720 = new BimEngine720('container', {
|
||||
fov: 75,
|
||||
enableZoom: true,
|
||||
enableRotate: true,
|
||||
sphereRadius: 500
|
||||
});
|
||||
engine720.loadPanorama('https://example.com/panorama.png');
|
||||
current = engine720;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 原生 HTML 完整示例
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>iflow-engine Demo</title>
|
||||
<style>
|
||||
#bim-container {
|
||||
width: 100%;
|
||||
height: 100vh;
|
||||
}
|
||||
body { margin: 0; font-family: sans-serif; }
|
||||
#container { width: 100vw; height: 100vh; }
|
||||
.btn-group { position: fixed; top: 10px; left: 10px; z-index: 100; }
|
||||
.btn-group button { padding: 8px 16px; margin-right: 8px; cursor: pointer; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="bim-container"></div>
|
||||
<div class="btn-group">
|
||||
<button onclick="switchTo3D()">3D 引擎</button>
|
||||
<button onclick="switchTo2D()">2D 图纸</button>
|
||||
<button onclick="switchTo720()">720° 全景</button>
|
||||
</div>
|
||||
<div id="container"></div>
|
||||
|
||||
<script type="module">
|
||||
import { BimEngine } from './lib/iflow-engine.es.js';
|
||||
<script src="./lib/iflow-engine.umd.js"></script>
|
||||
<script>
|
||||
var BimEngine = IflowEngine.BimEngine;
|
||||
var BimEngine2d = IflowEngine.BimEngine2d;
|
||||
var BimEngine720 = IflowEngine.BimEngine720;
|
||||
|
||||
const engine = new BimEngine('bim-container', {
|
||||
locale: 'zh-CN',
|
||||
theme: 'light'
|
||||
});
|
||||
var current = null;
|
||||
|
||||
// 初始化 3D 引擎
|
||||
engine.engine?.initialize();
|
||||
function destroyCurrent() {
|
||||
if (current) { current.destroy(); current = null; }
|
||||
}
|
||||
|
||||
// 加载模型
|
||||
engine.engine?.loadModel('./models/building.gltf');
|
||||
function switchTo3D() {
|
||||
destroyCurrent();
|
||||
var engine = new BimEngine('container', { locale: 'zh-CN', theme: 'dark' });
|
||||
engine.engine.initialize({ backgroundColor: 0x333333, showViewCube: true });
|
||||
engine.engine.loadModel(['https://example.com/model/']);
|
||||
current = engine;
|
||||
}
|
||||
|
||||
function switchTo2D() {
|
||||
destroyCurrent();
|
||||
var engine2d = new BimEngine2d('container', { theme: 'dark', gridEnabled: true });
|
||||
engine2d.loadDrawing('https://example.com/drawing-id');
|
||||
current = engine2d;
|
||||
}
|
||||
|
||||
function switchTo720() {
|
||||
destroyCurrent();
|
||||
var engine720 = new BimEngine720('container', {
|
||||
fov: 75, enableZoom: true, enableRotate: true, sphereRadius: 500
|
||||
});
|
||||
engine720.loadPanorama('https://example.com/panorama.png');
|
||||
current = engine720;
|
||||
}
|
||||
|
||||
// 默认加载 3D
|
||||
switchTo3D();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
## 主题切换
|
||||
|
||||
```typescript
|
||||
// 切换到暗色主题
|
||||
engine.setTheme('dark');
|
||||
|
||||
// 切换到亮色主题
|
||||
engine.setTheme('light');
|
||||
|
||||
// 自定义主题
|
||||
engine.setCustomTheme({
|
||||
name: 'custom',
|
||||
primary: '#ff6b6b',
|
||||
primaryHover: '#ff5252',
|
||||
primaryActive: '#ff4757',
|
||||
// ... 其他属性
|
||||
});
|
||||
```
|
||||
|
||||
## 语言切换
|
||||
|
||||
```typescript
|
||||
// 切换到英文
|
||||
engine.setLocale('en-US');
|
||||
|
||||
// 切换到中文
|
||||
engine.setLocale('zh-CN');
|
||||
```
|
||||
|
||||
## 工具栏操作
|
||||
|
||||
```typescript
|
||||
// 显示/隐藏工具栏
|
||||
engine.toolbar?.show();
|
||||
engine.toolbar?.hide();
|
||||
|
||||
// 添加自定义按钮
|
||||
engine.toolbar?.addButton({
|
||||
id: 'custom-btn',
|
||||
type: 'button',
|
||||
label: '自定义',
|
||||
icon: '<svg>...</svg>',
|
||||
onClick: () => {
|
||||
console.log('Custom button clicked');
|
||||
}
|
||||
});
|
||||
|
||||
// 设置按钮激活状态
|
||||
engine.toolbar?.setBtnActive('measure', true);
|
||||
```
|
||||
|
||||
## 测量功能
|
||||
|
||||
```typescript
|
||||
// 显示测量面板
|
||||
engine.measure?.show();
|
||||
|
||||
// 切换测量模式
|
||||
engine.measure?.switchMode('distance'); // 距离
|
||||
engine.measure?.switchMode('angle'); // 角度
|
||||
engine.measure?.switchMode('volume'); // 体积
|
||||
engine.measure?.switchMode('elevation'); // 标高
|
||||
engine.measure?.switchMode('slope'); // 坡度
|
||||
|
||||
// 获取测量配置
|
||||
const config = engine.measure?.getConfig();
|
||||
console.log(config); // { unit: 'mm', precision: 2 }
|
||||
|
||||
// 设置测量配置
|
||||
engine.measure?.setConfig({ unit: 'cm', precision: 1 });
|
||||
|
||||
// 清除所有测量结果
|
||||
engine.measure?.clearAll();
|
||||
```
|
||||
|
||||
## 剖切功能
|
||||
|
||||
### 平面剖切
|
||||
|
||||
```typescript
|
||||
// 显示剖切面板
|
||||
engine.sectionPlane?.show();
|
||||
|
||||
// 隐藏剖切面板
|
||||
engine.sectionPlane?.hide();
|
||||
```
|
||||
|
||||
### 轴向剖切
|
||||
|
||||
```typescript
|
||||
// 显示轴向剖切
|
||||
engine.sectionAxis?.show();
|
||||
|
||||
// 设置剖切轴向
|
||||
engine.sectionAxis?.setActiveAxis('x'); // X 轴
|
||||
engine.sectionAxis?.setActiveAxis('y'); // Y 轴
|
||||
engine.sectionAxis?.setActiveAxis('z'); // Z 轴
|
||||
```
|
||||
|
||||
### 剖切盒
|
||||
|
||||
```typescript
|
||||
// 显示剖切盒
|
||||
engine.sectionBox?.show();
|
||||
|
||||
// 获取剖切范围
|
||||
const range = engine.sectionBox?.getRange();
|
||||
console.log(range); // { minX, maxX, minY, maxY, minZ, maxZ }
|
||||
|
||||
// 设置剖切范围
|
||||
engine.sectionBox?.setRange({ minX: 0, maxX: 100 });
|
||||
|
||||
// 反向剖切
|
||||
engine.sectionBox?.setReversedState(true);
|
||||
```
|
||||
|
||||
## 漫游功能
|
||||
|
||||
```typescript
|
||||
// 显示漫游控制面板
|
||||
engine.walkControl?.show();
|
||||
|
||||
// 隐藏漫游控制面板
|
||||
engine.walkControl?.hide();
|
||||
```
|
||||
|
||||
## 事件监听
|
||||
|
||||
```typescript
|
||||
// 监听模型加载完成
|
||||
const unsubscribe = engine.on('engine:model-loaded', (payload) => {
|
||||
console.log('Model loaded:', payload.url);
|
||||
});
|
||||
|
||||
// 监听对象点击
|
||||
engine.on('engine:object-clicked', (payload) => {
|
||||
console.log('Object clicked:', payload.objectId, payload.position);
|
||||
});
|
||||
|
||||
// 监听主题变更
|
||||
engine.on('sys:theme-changed', (payload) => {
|
||||
console.log('Theme changed:', payload.theme);
|
||||
});
|
||||
|
||||
// 取消监听
|
||||
unsubscribe();
|
||||
```
|
||||
|
||||
## 销毁引擎
|
||||
|
||||
```typescript
|
||||
// 在组件卸载或页面关闭时销毁
|
||||
engine.destroy();
|
||||
```
|
||||
---
|
||||
|
||||
## TypeScript 类型
|
||||
|
||||
SDK 提供完整的 TypeScript 类型支持：
|
||||
SDK 导出所有相关类型，开箱即用：
|
||||
|
||||
```typescript
|
||||
import type {
|
||||
// 主入口
|
||||
BimEngine,
|
||||
|
||||
// 配置类型
|
||||
// 3D 引擎
|
||||
EngineOptions,
|
||||
ModelLoadOptions,
|
||||
|
||||
// 2D 引擎
|
||||
Engine2dOptions,
|
||||
DrawingLoadOptions,
|
||||
Drawing2dLayer,
|
||||
|
||||
// 720 引擎
|
||||
Engine720Options,
|
||||
PanoramaLoadOptions,
|
||||
PanoramaAnnotation,
|
||||
|
||||
// 通用
|
||||
ThemeConfig,
|
||||
ThemeType,
|
||||
EngineEvents,
|
||||
|
||||
// UI 组件（仅 BimEngine 3D 使用）
|
||||
DialogOptions,
|
||||
DialogPosition,
|
||||
ButtonConfig,
|
||||
ButtonGroupOptions,
|
||||
TreeOptions,
|
||||
TreeNodeConfig,
|
||||
TreeNodeCheckState,
|
||||
CollapseOptions,
|
||||
CollapseItemConfig,
|
||||
DescriptionOptions,
|
||||
DescriptionItem,
|
||||
|
||||
// 主题类型
|
||||
ThemeConfig,
|
||||
ThemeType,
|
||||
|
||||
// 事件类型
|
||||
EngineEvents,
|
||||
} from 'iflow-engine';
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
---
|
||||
|
||||
### 1. 模型加载失败
|
||||
## 主题与语言
|
||||
|
||||
- 检查模型 URL 是否正确
|
||||
- 确保模型格式受支持（GLTF/GLB/IFC）
|
||||
- 检查 CORS 配置
|
||||
三个引擎类均支持主题切换和语言设置：
|
||||
|
||||
### 2. 工具栏不显示
|
||||
```typescript
|
||||
// 构造时设置
|
||||
const engine = new BimEngine('container', { theme: 'dark', locale: 'zh-CN' });
|
||||
const engine2d = new BimEngine2d('container', { theme: 'light' });
|
||||
const engine720 = new BimEngine720('container', { theme: 'dark' });
|
||||
|
||||
- 确保容器有足够的尺寸
|
||||
- 检查是否调用了 `engine.initialize()`
|
||||
// 运行时切换主题
|
||||
engine.setTheme('light');
|
||||
engine2d.setTheme('dark');
|
||||
engine720.setTheme('light');
|
||||
|
||||
### 3. 主题不生效
|
||||
// 运行时切换语言（仅 3D 引擎支持）
|
||||
engine.setLocale('en-US');
|
||||
|
||||
- 确保在引擎初始化后再设置主题
|
||||
- 检查自定义主题配置是否完整
|
||||
|
||||
### 4. 内存泄漏
|
||||
|
||||
- 确保在组件卸载时调用 `engine.destroy()`
|
||||
- 取消不再需要的事件监听
|
||||
|
||||
## 下一步
|
||||
|
||||
- 查看 [架构文档](架构设计.md) 了解设计原理
|
||||
- 查看 [模块文档](MODULES/模块索引.md) 了解详细 API
|
||||
- 查看 [demo](../demo/) 获取更多示例
|
||||
// 自定义主题（仅 3D 引擎支持）
|
||||
engine.setCustomTheme({
|
||||
name: 'custom',
|
||||
primary: '#1890ff',
|
||||
primaryHover: '#40a9ff',
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**文档生成时间**: 2026-01-23
|
||||
**文档版本**: 1.0.0
|
||||
## 常见问题
|
||||
|
||||
### 1. 如何只引入需要的引擎？
|
||||
|
||||
直接按需 import，构建工具会自动 tree-shaking 未使用的代码：
|
||||
|
||||
```typescript
|
||||
// 只用 2D，不会打包 3D 和 720 的代码
|
||||
import { BimEngine2d } from 'iflow-engine';
|
||||
```
|
||||
|
||||
### 2. 多个引擎能同时存在吗？
|
||||
|
||||
可以，但需要**不同的容器**。同一个容器同时只能挂载一个引擎实例：
|
||||
|
||||
```typescript
|
||||
const engine3d = new BimEngine('container-3d', { theme: 'dark' });
|
||||
const engine2d = new BimEngine2d('container-2d', { theme: 'dark' });
|
||||
const engine720 = new BimEngine720('container-720', { theme: 'dark' });
|
||||
```
|
||||
|
||||
### 3. 切换引擎时页面闪烁
|
||||
|
||||
确保先调用 `destroy()` 再创建新实例。`destroy()` 会清空容器内容。
|
||||
|
||||
### 4. 模型/图纸加载失败
|
||||
|
||||
- 检查 URL 是否可访问
|
||||
- 检查浏览器控制台是否有 CORS 错误
|
||||
- 确保使用 HTTP 服务器运行（不能直接打开 HTML 文件）
|
||||
|
||||
### 5. 页面关闭时如何释放资源？
|
||||
|
||||
务必调用 `destroy()` 释放 WebGL 上下文和事件监听：
|
||||
|
||||
```typescript
|
||||
window.addEventListener('beforeunload', () => {
|
||||
engine?.destroy();
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
- [架构设计](架构设计.md) — 了解 Manager 模式和分层架构
|
||||
- [引擎 API 对接](引擎API对接.md) — 底层引擎 API 详细说明
|
||||
- [API 调用链](API调用链.md) — 调用关系与数据流
|
||||
- [demo/](../demo/) — 完整可运行示例
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: 2.0.0 | **更新日期**: 2026-03-10
|
||||
|
||||
77
docs/文档索引.md
77
docs/文档索引.md
@@ -7,74 +7,83 @@
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **名称** | iflow-engine |
|
||||
| **版本** | 1.0.1 |
|
||||
| **描述** | BIM 3D 引擎 SDK，支持 Vue2、Vue3、React 和原生 HTML |
|
||||
| **版本** | 2.2.1 |
|
||||
| **描述** | BIM 引擎 SDK，支持 3D 模型、2D 图纸、720° 全景，适用于 Vue2、Vue3、React 和原生 HTML |
|
||||
| **类型** | 技术项目 / SDK |
|
||||
| **语言** | TypeScript |
|
||||
| **构建工具** | Vite |
|
||||
| **核心依赖** | Three.js, iflow-engine-base |
|
||||
|
||||
## 快速导航
|
||||
|
||||
| 文档 | 说明 | 适合人群 |
|
||||
|------|------|---------|
|
||||
| [架构设计.md](架构设计.md) | 架构设计、设计模式、模块依赖 | 架构师、核心开发 |
|
||||
| [快速开始.md](快速开始.md) | 快速开始、安装、基础用法 | 新用户、集成开发 |
|
||||
| [快速开始.md](快速开始.md) | 快速开始、安装、基础用法（含 3D/2D/720） | 新用户、集成开发 |
|
||||
| [MODULES/模块索引.md](MODULES/模块索引.md) | 所有模块的详细文档索引 | 所有开发者 |
|
||||
| [ENGINNE_3D/API文档.md](ENGINNE_3D/API文档.md) | 3D 引擎底层 API 参考 | 3D 引擎开发者 |
|
||||
| [ENGINE_2D/API文档.md](ENGINE_2D/API文档.md) | 2D 图纸引擎 API 参考 | 2D 引擎开发者 |
|
||||
| [ENGINE_720/API文档.md](ENGINE_720/API文档.md) | 720° 全景引擎 API 参考 | 720 引擎开发者 |
|
||||
| [贡献指南.md](贡献指南.md) | 开发协作、脚本说明、最小验证集 | 项目贡献者 |
|
||||
| [运维手册.md](运维手册.md) | 构建/发布/回滚流程与常见问题 | 维护者 |
|
||||
| [API调用链.md](API调用链.md) | API 调用链（用户交互 → Manager → Engine → 底层引擎） | SDK 维护者 |
|
||||
|
||||
## 模块概览
|
||||
|
||||
```
|
||||
src/
|
||||
├── bim-engine.ts # 主入口类 BimEngine
|
||||
├── bim-engine.ts # 3D 引擎主入口类 BimEngine
|
||||
├── bim-engine-2d.ts # 2D 图纸引擎 BimEngine2d（独立轻量）
|
||||
├── bim-engine-720.ts # 720° 全景引擎 BimEngine720（独立轻量）
|
||||
├── index.ts # 导出文件
|
||||
├── core/ # 核心基础设施
|
||||
├── managers/ # 管理器层（业务逻辑）
|
||||
├── components/ # UI 组件层
|
||||
├── managers/ # 管理器层（仅 3D 使用）
|
||||
├── components/ # 组件层（engine / engine-2d / engine-720 + UI 组件）
|
||||
├── services/ # 全局服务（主题、国际化）
|
||||
├── themes/ # 主题预设和类型
|
||||
├── locales/ # 国际化文案
|
||||
├── types/ # 公共类型定义
|
||||
└── utils/ # 工具函数
|
||||
```
|
||||
|
||||
## 引擎类概览
|
||||
|
||||
| 引擎类 | 路径 | 定位 | 文档 |
|
||||
|--------|------|------|------|
|
||||
| **BimEngine** | `src/bim-engine.ts` | 3D 完整引擎（含工具栏、测量、剖切等 UI） | [快速开始](快速开始.md#一3d-引擎bimengine) |
|
||||
| **BimEngine2d** | `src/bim-engine-2d.ts` | 2D 图纸引擎（轻量独立） | [快速开始](快速开始.md#二2d-图纸引擎bimengine2d) / [API](ENGINE_2D/API文档.md) |
|
||||
| **BimEngine720** | `src/bim-engine-720.ts` | 720° 全景引擎（轻量独立） | [快速开始](快速开始.md#三720-全景引擎bimengine720) / [API](ENGINE_720/API文档.md) |
|
||||
|
||||
## 核心模块
|
||||
|
||||
| 模块 | 路径 | 职责 | 文档 |
|
||||
|------|------|------|------|
|
||||
| **BimEngine** | `src/bim-engine.ts` | 主入口类，整合所有功能 | 暂无独立文档 |
|
||||
| **core** | `src/core/` | 事件系统、管理器基类、注册表 | [详情](MODULES/核心模块.md) |
|
||||
| **managers** | `src/managers/` | 15 个管理器，处理业务逻辑 | [详情](MODULES/管理器模块.md) |
|
||||
| **components** | `src/components/` | 20+ 个 UI 组件 | [详情](MODULES/组件模块.md) |
|
||||
| **managers** | `src/managers/` | 15 个管理器，处理业务逻辑（仅 3D） | [详情](MODULES/管理器模块.md) |
|
||||
| **components** | `src/components/` | 引擎组件 + 20+ UI 组件 | [详情](MODULES/组件模块.md) |
|
||||
| **services** | `src/services/` | 主题管理、国际化服务 | [详情](MODULES/服务模块.md) |
|
||||
|
||||
## 架构分层
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ BimEngine (主引擎) │ ← 用户 API 入口
|
||||
├─────────────────────────────────────┤
|
||||
│ ManagerRegistry (单例注册表) │ ← 全局状态管理
|
||||
├─────────────────────────────────────┤
|
||||
│ 管理器层 (15个Manager类) │ ← 业务逻辑
|
||||
├─────────────────────────────────────┤
|
||||
│ 组件层 (20+ UI组件) │ ← 视图渲染
|
||||
├─────────────────────────────────────┤
|
||||
│ 服务层 (LocaleManager, ThemeManager) │ ← 横切关注点
|
||||
├─────────────────────────────────────┤
|
||||
│ 核心基础设施 │ ← 事件、基类
|
||||
│ (EventEmitter, BaseManager) │
|
||||
└─────────────────────────────────────┘
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ BimEngine (3D) BimEngine2d (2D) BimEngine720 (720)│ ← 用户 API 入口
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ManagerRegistry│ │ManagerRegistry│ │ManagerRegistry│ │
|
||||
│ │ + 15 Managers │ │ (仅事件总线) │ │ (仅事件总线) │ │
|
||||
│ │ + 20+ UI 组件 │ │ + Engine2d │ │ + Engine720 │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 服务层: LocaleManager (全局), ThemeManager (全局) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 核心: EventEmitter, BaseManager │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 底层: iflow-engine-base (createEngine/createEngine2d/720) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 关键设计模式
|
||||
|
||||
| 模式 | 应用位置 | 说明 |
|
||||
|------|---------|------|
|
||||
| **单例模式** | ManagerRegistry, LocaleManager, ThemeManager | 全局唯一实例 |
|
||||
| **实例模式** | ManagerRegistry | 每个引擎实例独立注册表 |
|
||||
| **单例模式** | LocaleManager, ThemeManager | 全局共享服务 |
|
||||
| **观察者模式** | EventEmitter, 服务订阅 | 事件驱动通信 |
|
||||
| **模板方法** | BaseManager, BaseDialogManager | 统一生命周期 |
|
||||
| **工厂模式** | BimEngine 初始化 | 创建管理器实例 |
|
||||
@@ -83,18 +92,18 @@ src/
|
||||
|
||||
| 类别 | 数量 |
|
||||
|------|------|
|
||||
| 管理器类 | 15 个 |
|
||||
| UI 组件 | 20+ 个 |
|
||||
| 引擎类 | 3 个（BimEngine / BimEngine2d / BimEngine720） |
|
||||
| 管理器类 | 15 个（仅 3D） |
|
||||
| UI 组件 | 20+ 个（仅 3D） |
|
||||
| 事件类型 | 30+ 个 |
|
||||
| 主题属性 | 70+ 个 |
|
||||
| 国际化键 | 200+ 个 |
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **语言**: TypeScript 5.x
|
||||
- **构建**: Vite 7.x
|
||||
- **3D 引擎**: Three.js 0.182.x
|
||||
- **核心 SDK**: iflow-engine-base 1.0.x
|
||||
- **核心 SDK**: iflow-engine-base 3.1.x
|
||||
|
||||
## 相关链接
|
||||
|
||||
@@ -103,5 +112,5 @@ src/
|
||||
|
||||
---
|
||||
|
||||
**文档生成时间**: 2026-01-23
|
||||
**文档版本**: 1.0.0
|
||||
**文档生成时间**: 2026-03-10
|
||||
**文档版本**: 2.0.0
|
||||
|
||||
96
docs/架构设计.md
96
docs/架构设计.md
@@ -2,32 +2,45 @@
|
||||
|
||||
## 概述
|
||||
|
||||
iflow-engine 采用分层架构：`BimEngine` 作为入口，`ManagerRegistry` 作为实例级注册表，Manager 层负责编排，Component 层负责 UI/引擎封装，Services/Core 层提供基础能力。
|
||||
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 不再通过 `registry.engine3d?.xxx()` 间接透传，而是通过 `BaseManager.engineComponent` 直接访问 `Engine` 组件
|
||||
- 非 Manager 组件（如 toolbar 按钮、walk-path-panel）通过 `registry.engine3d?.getEngineComponent()?.xxx()` 访问 `Engine`
|
||||
- 内部 Manager 统一通过 `BaseManager.engineComponent` 直接访问 `Engine` 组件
|
||||
- `Engine.getEngine()` 已移除，改为 `onRawEvent()/offRawEvent()` 订阅底层事件
|
||||
|
||||
---
|
||||
|
||||
## 分层结构
|
||||
|
||||
```text
|
||||
BimEngine (入口 / Facade)
|
||||
└─ ManagerRegistry (实例级，不是全局单例)
|
||||
├─ Managers (业务编排)
|
||||
│ ├─ EngineManager (公共 API + 初始化 + 右键菜单组装)
|
||||
│ ├─ *DialogManager / *ControlManager
|
||||
│ └─ ...
|
||||
├─ Components (UI + Engine 封装)
|
||||
│ ├─ Engine (封装 iflow-engine-base)
|
||||
│ ├─ Dialog/Toolbar/Panel...
|
||||
│ └─ ...
|
||||
├─ Services (Theme / Locale)
|
||||
└─ Core (EventEmitter / BaseManager / BaseDialogManager)
|
||||
┌───────────────────────────────────────────────────────────────────┐
|
||||
│ 用户 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)
|
||||
```
|
||||
|
||||
---
|
||||
@@ -151,3 +164,54 @@ SectionBoxDialogManager (BaseDialogManager)
|
||||
## 后续建议
|
||||
|
||||
当前已完成“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
|
||||
|
||||
Reference in New Issue
Block a user