bim_engine/docs/ENGINE_2D/API文档.md

2D 图纸引擎 API 文档

概述

BimEngine2d 是独立的 2D CAD/DWG 图纸查看引擎。轻量级设计，不依赖 3D 引擎的 UI 管理器（toolbar、measure 等），构造时自动初始化。

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

---

导入

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

// UMD
const { BimEngine2d } = IflowEngine;

---

BimEngine2d

构造函数

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

参数:

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

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

BimEngine2dOptions

interface BimEngine2dOptions {
  /** 语言 */
locale?: 'zh-CN' | 'zh-TW' | 'en-US';
  /** 主题 */
  theme?: 'dark' | 'light';
  /** 背景颜色（十六进制数值，如 0xffffff） */
  backgroundColor?: number;
  /** 是否启用网格 */
  gridEnabled?: boolean;
  /** 是否启用坐标轴 */
  axesEnabled?: boolean;
  /** 选中构件颜色 */
  selectionColor?: number;
  /** 高亮构件颜色 */
  highlightColor?: number;
  /** 是否启用性能监控 */
  enablePerformanceMonitoring?: boolean;
}

---

图纸操作

loadDrawing()

public async loadDrawing(url: string, options?: DrawingLoadOptions): Promise<void>

功能: 加载 2D 图纸

参数:

• url: string — 图纸资源 URL
• options: DrawingLoadOptions — 加载选项（可选）

返回值: Promise<void>

interface DrawingLoadOptions {
  /** 分块大小 */
  chunkSize?: number;
  /** 是否启用分块加载 */
  enableChunkedLoading?: boolean;
  /** 是否启用数据校验 */
  enableValidation?: boolean;
}

示例:

await engine2d.loadDrawing('https://example.com/drawing-id');

getLayers()

public getLayers(): Drawing2dLayer[]

功能: 获取当前图纸的所有图层

返回值: Drawing2dLayer[]

interface Drawing2dLayer {
  /** 图层名称 */
  name: string;
  /** 图层是否可见 */
  visible: boolean;
}

示例:

const layers = engine2d.getLayers();
layers.forEach(layer => {
  console.log(`${layer.name}: ${layer.visible ? '可见' : '隐藏'}`);
});

setLayerVisible()

public setLayerVisible(name: string, visible: boolean): void

功能: 设置指定图层的可见性

参数:

• name: string — 图层名称
• visible: boolean — 是否可见

示例:

engine2d.setLayerVisible('标注层', false);  // 隐藏标注层
engine2d.setLayerVisible('墙体', true);     // 显示墙体层

---

视图控制

resetView()

public resetView(): void

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

fitToView()

public fitToView(): void

功能: 缩放到适应全部图纸内容

setZoom()

public setZoom(zoom: number): void

功能: 设置缩放级别

参数:

• zoom: number — 缩放值

getZoom()

public getZoom(): number

功能: 获取当前缩放级别

返回值: number — 当前缩放值，默认 1

---

主题

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 = engine2d.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

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

offRawEvent()

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

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

---

生命周期

destroy()

public destroy(): void

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

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

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

---

内部架构

BimEngine2d (用户 API)
  ├─ ManagerRegistry (仅事件总线，不注册 Manager)
  └─ Engine2d 组件 (IBimComponent)
       └─ createEngine2d() (iflow-engine-base)

与 BimEngine（3D）的关键区别：

	BimEngine (3D)	BimEngine2d (2D)
Manager 层	15 个 Manager	无（跳过 Manager 层）
UI 组件	toolbar、dialog、menu 等	无
初始化	需要调用 engine.initialize()	构造时自动初始化
ManagerRegistry	完整注册所有 Manager	仅用于事件发射

---

文档版本: 1.0.0 | 更新日期: 2026-03-10