bim_xg/bim_engine

Fork 0

Files

yuding dd4600bb5b 提交代码

2026-03-16 16:13:36 +08:00

5.6 KiB

Raw Blame History

720° 全景引擎 API 文档

概述

BimEngine720 是独立的 720° 全景图查看引擎。轻量级设计，支持鼠标/触摸旋转和缩放，不依赖 3D 引擎的 UI 管理器，构造时自动初始化。

文件路径: src/bim-engine-720.ts 底层依赖: iflow-engine-base 的 createEngine720()

导入

// ESM
import { BimEngine720 } from 'iflow-engine';

// UMD
const { BimEngine720 } = IflowEngine;

BimEngine720

构造函数

constructor(container: HTMLElement | string, options?: BimEngine720Options)

参数:

参数	类型	必填	说明
`container`	`HTMLElement \| string`	✅	DOM 元素或元素 ID
`options`	`BimEngine720Options`		构造选项

构造时自动初始化引擎，无需额外调用 initialize() 方法。

BimEngine720Options

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()

public async loadPanorama(url: string, options?: PanoramaLoadOptions): Promise<void>

功能: 加载全景图

参数:

url: string — 全景图片 URL（等距柱状投影格式）
options: PanoramaLoadOptions — 加载选项（可选）

返回值: Promise<void>

interface PanoramaLoadOptions {
  /** 加载超时时间（毫秒） */
  timeout?: number;
}

示例:

await engine720.loadPanorama('https://example.com/panorama.png');

preloadPanoramas()

public async preloadPanoramas(urls: string[]): Promise<void>

功能: 预加载多个全景图（用于场景切换时减少加载等待）

参数:

urls: string[] — 全景图片 URL 数组

示例:

await engine720.preloadPanoramas([
  'https://example.com/room1.png',
  'https://example.com/room2.png',
  'https://example.com/room3.png'
]);

视角控制

setFov()

public setFov(fov: number): void

功能: 设置视场角（Field of View）

参数:

fov: number — 视场角度数

getFov()

public getFov(): number

功能: 获取当前视场角

返回值: number — 当前视场角，默认 75

lookAt()

public lookAt(phi: number, theta: number, animated?: boolean): void

功能: 设置相机朝向（球面坐标）

参数:

phi: number — 水平角度
theta: number — 垂直角度
animated: boolean — 是否动画过渡（可选）

示例:

// 看向指定方向
engine720.lookAt(Math.PI / 4, Math.PI / 6, true);

resetView()

public resetView(): void

功能: 重置视角到初始状态

主题

setTheme()

public setTheme(theme: 'dark' | 'light'): void

功能: 切换主题

参数:

theme: 'dark' | 'light'

事件

on()

public on<K extends keyof EngineEvents>(
  event: K,
  listener: (payload: EngineEvents[K]) => void
): () => void

功能: 订阅事件

返回值: 取消订阅函数

示例:

const unsub = engine720.on('engine:model-loaded', (payload) => {
  console.log('全景图加载完成');
});

// 取消订阅
unsub();

off()

public off<K extends keyof EngineEvents>(
  event: K,
  listener: (payload: EngineEvents[K]) => void
): void

功能: 取消事件订阅

onRawEvent()

public onRawEvent(event: string, handler: (...args: any[]) => void): void

功能: 订阅底层 720 引擎的原始事件

offRawEvent()

public offRawEvent(event: string, handler: (...args: any[]) => void): void

功能: 取消订阅底层 720 引擎的原始事件

生命周期

destroy()

public destroy(): void

功能: 销毁引擎，释放所有资源

销毁底层 Engine720 组件
重置 ManagerRegistry
调用后实例不可再使用

重要: 切换引擎类型或页面卸载时务必调用。

内部架构

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	仅用于事件发射

5.6 KiB Raw Blame History Unescape Escape