提交代码

docs/ENGINE_720/API文档.md

@@ -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