308 lines
5.6 KiB
Markdown
308 lines
5.6 KiB
Markdown
# 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' | 'zh-TW' | '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
|