613 lines
15 KiB
Markdown
613 lines
15 KiB
Markdown
# Engine 组件详细文档
|
||
|
||
> 本文档详细描述 Engine 组件的实现细节，包括 API、UI 结构、逻辑流程等，供 AI 根据文档重现组件。
|
||
|
||
---
|
||
|
||
## 1. 组件概述
|
||
|
||
### 1.1 基本信息
|
||
- **组件名称**: `Engine`
|
||
- **文件路径**: `src/components/engine/index.ts`
|
||
- **类型定义**: `src/components/engine/types.ts`
|
||
- **实现接口**: `IBimComponent`
|
||
- **用途**: 封装第三方 3D 引擎 SDK，提供统一的 3D 引擎管理接口
|
||
|
||
### 1.2 在 SDK 中的位置
|
||
- Engine 组件是独立的 3D 引擎组件
|
||
- 必须通过 `EngineManager` 使用，不允许直接使用
|
||
- `EngineManager` 位于 `src/managers/engine-manager.ts`
|
||
- 采用延迟初始化模式，需要用户主动调用 `init()` 方法
|
||
|
||
### 1.3 第三方 SDK 依赖
|
||
- 依赖 `src/bim-engine-sdk.es.js` 中的 `createEngine` 函数
|
||
- 通过依赖注入方式使用，不直接导入
|
||
|
||
---
|
||
|
||
## 2. 组件类 API 文档
|
||
|
||
### 2.1 构造函数
|
||
|
||
```typescript
|
||
constructor(options: EngineOptions)
|
||
```
|
||
|
||
**参数**:
|
||
- `options`: `EngineOptions` - 3D 引擎配置选项
|
||
|
||
**默认配置**:
|
||
```typescript
|
||
{
|
||
backgroundColor: 0x1a1a1a, // 默认深色背景
|
||
version: 'v1', // 默认使用 v1 版本
|
||
showStats: false, // 默认不显示统计
|
||
showViewCube: true // 默认显示视图立方体
|
||
}
|
||
```
|
||
|
||
**行为**:
|
||
- 解析容器元素
|
||
- 如果容器没有 id，生成一个唯一的 id
|
||
- 保存配置选项（设置默认值）
|
||
|
||
### 2.2 公共方法
|
||
|
||
#### `init(): void`
|
||
初始化组件（实现 `IBimComponent` 接口）
|
||
|
||
**功能**:
|
||
- 检查是否已初始化或已销毁
|
||
- 创建引擎配置对象
|
||
- 调用 `createEngineSDK()` 创建引擎实例
|
||
- 标记为已初始化
|
||
- 订阅主题变化
|
||
- 应用当前主题
|
||
|
||
**错误处理**:
|
||
- 如果创建失败，抛出错误并标记为未初始化
|
||
|
||
#### `setTheme(theme: ThemeConfig): void`
|
||
设置主题（实现 `IBimComponent` 接口）
|
||
|
||
**参数**:
|
||
- `theme`: `ThemeConfig` - 全局主题配置
|
||
|
||
**功能**:
|
||
- 根据主题名称选择背景色：
|
||
- `dark`: 使用深色背景 `0x1a1a1a`
|
||
- `light`: 使用浅色背景 `0xf5f5f5`
|
||
- `custom`: 使用配置中的 `backgroundColor` 或默认值
|
||
- 尝试更新引擎背景色：
|
||
- 如果引擎有 `setBackgroundColor()` 方法，调用它
|
||
- 否则，如果引擎有 `scene.background`，设置其颜色
|
||
|
||
#### `setLocales(): void`
|
||
设置语言（实现 `IBimComponent` 接口）
|
||
|
||
**功能**:
|
||
- 3D 引擎组件暂时不需要本地化
|
||
- 方法为空实现
|
||
|
||
#### `isInitialized(): boolean`
|
||
检查是否已初始化
|
||
|
||
**返回**: `boolean` - 是否已初始化
|
||
|
||
#### `loadModel(url: string, options?: ModelLoadOptions): void`
|
||
加载 3D 模型
|
||
|
||
**参数**:
|
||
- `url`: `string` - 模型文件 URL（必需）
|
||
- `options`: `ModelLoadOptions` (可选) - 加载选项
|
||
|
||
**功能**:
|
||
- 检查引擎是否已初始化
|
||
- 检查 URL 是否提供
|
||
- 调用引擎的 `loader.loadModel()` 方法加载模型
|
||
|
||
**加载选项**:
|
||
- `position`: `[number, number, number]` - 模型位置 [x, y, z]
|
||
- `rotation`: `[number, number, number]` - 模型旋转（弧度）[x, y, z]
|
||
- `scale`: `[number, number, number]` - 模型缩放 [x, y, z]
|
||
- `id`: `string` - 模型 ID（可选）
|
||
|
||
#### `getEngine(): any`
|
||
获取原始 3D 引擎实例
|
||
|
||
**返回**: 第三方 3D 引擎实例或 `null`
|
||
|
||
**功能**:
|
||
- 返回底层 3D 引擎实例
|
||
- 用于直接调用第三方引擎的其他 API
|
||
|
||
#### `destroy(): void`
|
||
销毁组件（实现 `IBimComponent` 接口）
|
||
|
||
**功能**:
|
||
- 取消主题订阅
|
||
- 清空容器内容
|
||
- 标记为已销毁和未初始化
|
||
|
||
**注意**: 不销毁引擎实例本身（由第三方 SDK 管理）
|
||
|
||
---
|
||
|
||
## 3. 分化组件说明
|
||
|
||
**Engine 组件没有分化组件**。
|
||
|
||
---
|
||
|
||
## 4. Manager API 文档
|
||
|
||
### 4.1 EngineManager 类
|
||
|
||
**文件路径**: `src/managers/engine-manager.ts`
|
||
|
||
**继承关系**: `EngineManager extends BimComponent`
|
||
|
||
### 4.2 构造函数
|
||
|
||
```typescript
|
||
constructor(engine: BimEngine, container: HTMLElement)
|
||
```
|
||
|
||
**参数**:
|
||
- `engine`: `BimEngine` - 引擎实例
|
||
- `container`: `HTMLElement` - 3D 引擎挂载的目标容器
|
||
|
||
**行为**:
|
||
- 保存容器引用
|
||
- **不自动初始化引擎**（延迟初始化模式）
|
||
|
||
### 4.3 公共方法
|
||
|
||
#### `initialize(options?: Omit<EngineOptions, 'container'>): boolean`
|
||
初始化 3D 引擎
|
||
|
||
**参数**:
|
||
- `options`: `Omit<EngineOptions, 'container'>` (可选) - 引擎配置选项
|
||
|
||
**返回**: `boolean` - 是否初始化成功
|
||
|
||
**功能**:
|
||
- 如果已经初始化，先销毁旧的实例
|
||
- 创建 `Engine` 组件实例
|
||
- 调用组件的 `init()` 方法初始化引擎
|
||
- 返回初始化结果
|
||
|
||
**错误处理**:
|
||
- 如果初始化失败，返回 `false` 并输出错误信息
|
||
|
||
#### `isInitialized(): boolean`
|
||
检查 3D 引擎是否已初始化
|
||
|
||
**返回**: `boolean` - 是否已初始化
|
||
|
||
#### `loadModel(url: string, options?: ModelLoadOptions): void`
|
||
加载 3D 模型
|
||
|
||
**参数**:
|
||
- `url`: `string` - 模型文件 URL
|
||
- `options`: `ModelLoadOptions` (可选) - 加载选项
|
||
|
||
**功能**:
|
||
- 检查引擎是否已初始化
|
||
- 如果未初始化，输出错误信息
|
||
- 调用引擎组件的 `loadModel()` 方法
|
||
|
||
#### `getEngine(): any`
|
||
获取原始 3D 引擎实例
|
||
|
||
**返回**: 第三方 3D 引擎实例或 `null`
|
||
|
||
**功能**:
|
||
- 用于直接调用第三方引擎的其他 API
|
||
- 如果引擎未初始化，返回 `null` 并输出警告
|
||
|
||
#### `destroy(): void`
|
||
销毁 3D 引擎实例
|
||
|
||
**功能**:
|
||
- 调用引擎组件的 `destroy()` 方法
|
||
- 清空引擎实例引用
|
||
|
||
---
|
||
|
||
## 5. UI 详细描述
|
||
|
||
### 5.1 DOM 结构
|
||
|
||
**Engine 组件不直接创建 UI 元素**，而是：
|
||
|
||
1. **使用容器元素**:
|
||
- 容器元素由外部提供（通过 `EngineOptions.container`）
|
||
- 如果容器没有 id，组件会生成一个唯一的 id
|
||
|
||
2. **第三方 SDK 创建 UI**:
|
||
- 第三方 SDK 的 `createEngine()` 函数会在容器内创建 3D 场景
|
||
- 可能包括：
|
||
- Canvas 元素（WebGL 渲染）
|
||
- 统计面板（如果 `showStats: true`）
|
||
- 视图立方体（如果 `showViewCube: true`）
|
||
|
||
### 5.2 容器 ID 生成
|
||
|
||
**算法**:
|
||
```typescript
|
||
containerId = `engine-container-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
|
||
```
|
||
|
||
**格式**: `engine-container-[时间戳]-[随机字符串]`
|
||
|
||
**示例**: `engine-container-1704067200000-k3j9x2m1p`
|
||
|
||
### 5.3 第三方 SDK 配置
|
||
|
||
**传递给 `createEngine()` 的配置对象**:
|
||
```typescript
|
||
{
|
||
containerId: string, // 容器 ID
|
||
backgroundColor: number, // 背景色（十六进制数字）
|
||
version: 'v1' | 'v2', // WebGL 版本
|
||
showStats: boolean, // 是否显示统计
|
||
showViewCube: boolean // 是否显示视图立方体
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 逻辑流程详细描述
|
||
|
||
### 6.1 初始化流程
|
||
|
||
1. **构造函数调用**:
|
||
- 解析容器元素
|
||
- 生成或使用容器 ID
|
||
- 保存配置选项（设置默认值）
|
||
|
||
2. **init() 方法执行**（用户主动调用）:
|
||
- 检查是否已初始化，如果是则返回
|
||
- 检查是否已销毁，如果是则报错
|
||
- 创建引擎配置对象
|
||
- 调用 `createEngineSDK()` 创建引擎实例
|
||
- 检查引擎实例是否创建成功
|
||
- 标记为已初始化
|
||
- 订阅主题变化：`themeManager.subscribe()`
|
||
- 应用当前主题
|
||
|
||
### 6.2 生命周期
|
||
|
||
#### 创建阶段
|
||
- 构造函数 → 保存配置
|
||
|
||
#### 初始化阶段（延迟）
|
||
- 用户调用 `init()` → 创建引擎实例 → 订阅主题
|
||
|
||
#### 运行阶段
|
||
- 响应主题变更：`setTheme()` 被调用
|
||
- 加载模型：`loadModel()` 被调用
|
||
- 用户交互：3D 场景交互（由第三方 SDK 处理）
|
||
|
||
#### 销毁阶段
|
||
- `destroy()` 被调用
|
||
- 取消主题订阅
|
||
- 清空容器
|
||
- 更新状态
|
||
|
||
### 6.3 主题变更流程
|
||
|
||
1. 主题变更 → `themeManager` 通知订阅者
|
||
2. `setTheme()` 方法被调用
|
||
3. 根据主题名称选择背景色：
|
||
- `dark` → `0x1a1a1a`
|
||
- `light` → `0xf5f5f5`
|
||
- `custom` → 使用配置值或默认值
|
||
4. 尝试更新引擎背景色：
|
||
- 方法 1: 调用 `engine.setBackgroundColor(backgroundColor)`
|
||
- 方法 2: 设置 `engine.scene.background.setHex(backgroundColor)`
|
||
|
||
### 6.4 模型加载流程
|
||
|
||
1. 用户调用 `loadModel(url, options)`
|
||
2. 检查引擎是否已初始化
|
||
3. 检查 URL 是否提供
|
||
4. 调用 `engine.loader.loadModel(url, options)`
|
||
5. 第三方 SDK 处理模型加载
|
||
|
||
### 6.5 状态管理
|
||
|
||
#### 内部状态
|
||
- `_isInitialized`: 是否已初始化
|
||
- `_isDestroyed`: 是否已销毁
|
||
- `engine`: 第三方 3D 引擎实例
|
||
- `containerId`: 容器 ID
|
||
- `options`: 引擎配置选项
|
||
|
||
#### 订阅管理
|
||
- `unsubscribeTheme`: 主题订阅取消函数
|
||
|
||
### 6.6 与其他组件的交互
|
||
|
||
- **与 EngineManager**: 通过 Manager 创建和管理
|
||
- **与 ThemeManager**: 订阅主题变更
|
||
- **与第三方 SDK**: 通过 `createEngine()` 函数创建引擎实例
|
||
|
||
---
|
||
|
||
## 7. 国际化支持
|
||
|
||
### 7.1 使用的翻译键
|
||
|
||
**Engine 组件不使用翻译键**（3D 引擎不需要国际化）。
|
||
|
||
### 7.2 语言变更处理
|
||
|
||
- `setLocales()` 方法为空实现
|
||
- 不订阅语言变更
|
||
|
||
---
|
||
|
||
## 8. 主题支持
|
||
|
||
### 8.1 使用的主题变量
|
||
|
||
- 根据主题名称选择背景色：
|
||
- `dark` 主题 → `0x1a1a1a`（深色背景）
|
||
- `light` 主题 → `0xf5f5f5`（浅色背景）
|
||
- `custom` 主题 → 使用配置值或默认值
|
||
|
||
### 8.2 主题变更处理
|
||
|
||
- 组件订阅 `themeManager.subscribe()`
|
||
- 主题变更时，`setTheme()` 方法被调用
|
||
- 根据主题名称选择背景色
|
||
- 尝试更新引擎背景色（通过引擎 API）
|
||
|
||
### 8.3 实现细节
|
||
|
||
```typescript
|
||
public setTheme(theme: ThemeConfig): void {
|
||
let backgroundColor: number;
|
||
if (theme.name === 'dark') {
|
||
backgroundColor = 0x1a1a1a;
|
||
} else if (theme.name === 'light') {
|
||
backgroundColor = 0xf5f5f5;
|
||
} else {
|
||
backgroundColor = this.options.backgroundColor ?? 0x1a1a1a;
|
||
}
|
||
|
||
// 尝试更新引擎背景色
|
||
if (this.engine && typeof this.engine.setBackgroundColor === 'function') {
|
||
this.engine.setBackgroundColor(backgroundColor);
|
||
} else if (this.engine && this.engine.scene) {
|
||
if (this.engine.scene.background) {
|
||
this.engine.scene.background.setHex(backgroundColor);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 使用示例
|
||
|
||
### 9.1 基本使用（通过 EngineManager）
|
||
|
||
```typescript
|
||
import { BimEngine } from 'bim-engine-sdk';
|
||
|
||
const engine = new BimEngine('container');
|
||
|
||
// 初始化 3D 引擎（延迟初始化）
|
||
const success = engine.initEngine({
|
||
backgroundColor: 0x333333,
|
||
version: 'v1',
|
||
showStats: true,
|
||
showViewCube: true
|
||
});
|
||
|
||
if (success) {
|
||
console.log('3D 引擎初始化成功');
|
||
}
|
||
|
||
// 加载模型
|
||
engine.engine.loadModel('/model/building.glb', {
|
||
position: [0, 0, 0],
|
||
rotation: [0, 0, 0],
|
||
scale: [1, 1, 1]
|
||
});
|
||
```
|
||
|
||
### 9.2 高级使用
|
||
|
||
```typescript
|
||
// 检查引擎是否已初始化
|
||
if (engine.engine.isInitialized()) {
|
||
// 加载模型
|
||
engine.engine.loadModel('/model/model.glb');
|
||
}
|
||
|
||
// 获取原始引擎实例，调用第三方 API
|
||
const rawEngine = engine.engine.getEngine();
|
||
if (rawEngine) {
|
||
// 调用第三方 SDK 的其他方法
|
||
rawEngine.someOtherMethod();
|
||
}
|
||
```
|
||
|
||
### 9.3 主题切换
|
||
|
||
```typescript
|
||
// 切换主题会自动更新 3D 场景背景色
|
||
engine.setTheme('dark'); // 深色背景
|
||
engine.setTheme('light'); // 浅色背景
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 实现细节（供 AI 重现）
|
||
|
||
### 10.1 关键算法
|
||
|
||
#### 容器 ID 生成算法
|
||
```typescript
|
||
function generateContainerId(): string {
|
||
const timestamp = Date.now();
|
||
const random = Math.random().toString(36).substr(2, 9);
|
||
return `engine-container-${timestamp}-${random}`;
|
||
}
|
||
```
|
||
|
||
#### 主题背景色选择算法
|
||
```typescript
|
||
function selectBackgroundColor(theme: ThemeConfig, defaultColor: number): number {
|
||
if (theme.name === 'dark') {
|
||
return 0x1a1a1a; // 深色背景
|
||
} else if (theme.name === 'light') {
|
||
return 0xf5f5f5; // 浅色背景
|
||
} else {
|
||
return defaultColor; // 自定义主题，使用配置值
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 引擎背景色更新算法
|
||
```typescript
|
||
function updateEngineBackground(engine: any, color: number): void {
|
||
// 方法 1: 如果引擎有 setBackgroundColor 方法
|
||
if (engine && typeof engine.setBackgroundColor === 'function') {
|
||
engine.setBackgroundColor(color);
|
||
return;
|
||
}
|
||
|
||
// 方法 2: 如果引擎有 scene.background
|
||
if (engine && engine.scene && engine.scene.background) {
|
||
engine.scene.background.setHex(color);
|
||
return;
|
||
}
|
||
|
||
// 方法 3: 无法更新（引擎可能不支持）
|
||
}
|
||
```
|
||
|
||
### 10.2 性能优化点
|
||
|
||
1. **延迟初始化**:
|
||
- 引擎不自动初始化，由用户主动调用
|
||
- 减少不必要的资源消耗
|
||
|
||
2. **状态检查**:
|
||
- 初始化前检查状态，避免重复初始化
|
||
- 销毁后禁止初始化，避免错误
|
||
|
||
3. **错误处理**:
|
||
- 所有操作都有错误检查
|
||
- 提供有意义的错误信息
|
||
|
||
### 10.3 注意事项和边界情况
|
||
|
||
1. **容器 ID 唯一性**:
|
||
- 容器 ID 必须唯一
|
||
- 如果容器已有 id，使用现有 id
|
||
- 如果容器没有 id，生成唯一 id
|
||
|
||
2. **延迟初始化**:
|
||
- 引擎不会自动初始化
|
||
- 用户必须主动调用 `init()` 或 `initialize()`
|
||
- 初始化前调用其他方法会报错
|
||
|
||
3. **引擎实例管理**:
|
||
- 引擎实例由第三方 SDK 创建
|
||
- 组件不负责销毁引擎实例本身
|
||
- 只负责清理订阅和容器
|
||
|
||
4. **主题更新兼容性**:
|
||
- 不同第三方 SDK 的 API 可能不同
|
||
- 需要尝试多种方式更新背景色
|
||
- 如果都不支持，静默失败
|
||
|
||
5. **模型加载**:
|
||
- 模型 URL 必须是可访问的
|
||
- 模型格式由第三方 SDK 支持
|
||
- 加载选项由第三方 SDK 处理
|
||
|
||
6. **错误处理**:
|
||
- 初始化失败时，标记为未初始化
|
||
- 提供有意义的错误信息
|
||
- 不抛出未捕获的异常
|
||
|
||
7. **第三方 SDK 依赖**:
|
||
- 依赖 `bim-engine-sdk.es.js` 文件
|
||
- 通过动态导入或全局变量访问
|
||
- 需要确保 SDK 文件已加载
|
||
|
||
---
|
||
|
||
## 11. 类型定义
|
||
|
||
### 11.1 EngineOptions
|
||
|
||
```typescript
|
||
interface EngineOptions {
|
||
container: HTMLElement; // 容器元素（必需）
|
||
backgroundColor?: number; // 背景颜色（可选，默认 0x1a1a1a）
|
||
version?: 'v1' | 'v2'; // WebGL 版本（可选，默认 'v1'）
|
||
showStats?: boolean; // 是否显示性能统计（可选，默认 false）
|
||
showViewCube?: boolean; // 是否显示视图立方体（可选，默认 true）
|
||
}
|
||
```
|
||
|
||
### 11.2 ModelLoadOptions
|
||
|
||
```typescript
|
||
interface ModelLoadOptions {
|
||
position?: [number, number, number]; // 模型位置 [x, y, z]（可选）
|
||
rotation?: [number, number, number]; // 模型旋转（弧度）[x, y, z]（可选）
|
||
scale?: [number, number, number]; // 模型缩放 [x, y, z]（可选）
|
||
id?: string; // 模型 ID（可选）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 文件清单
|
||
|
||
### 12.1 相关文件
|
||
|
||
- `src/components/engine/index.ts` - 主组件类
|
||
- `src/components/engine/types.ts` - 类型定义
|
||
- `src/managers/engine-manager.ts` - 管理器类
|
||
- `src/bim-engine-sdk.es.js` - 第三方 SDK（依赖）
|
||
|
||
### 12.2 依赖文件
|
||
|
||
- `src/types/component.ts` - IBimComponent 接口
|
||
- `src/themes/types.ts` - ThemeConfig 类型
|
||
- `src/services/theme.ts` - ThemeManager
|
||
|
||
---
|
||
|
||
## 13. 更新记录
|
||
|
||
| 日期 | 修改内容 | 修改人 |
|
||
|------|---------|--------|
|
||
| 2024-XX-XX | 初始创建 | AI Assistant |
|
||
|
||
---
|
||
|
||
**重要提醒**: 本文档必须与组件代码保持同步。任何组件修改都必须更新本文档！
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|