bim_engine/docs/ENGINE_720/API文档.md

# 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