# 2D 图纸引擎 API 文档

## 概述

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

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

---

## 导入

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

// UMD
const { BimEngine2d } = IflowEngine;
```

---

## BimEngine2d

### 构造函数

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

**参数**:

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

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

### BimEngine2dOptions

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

---

## 图纸操作

### loadDrawing()

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

**功能**: 加载 2D 图纸

**参数**:
- `url`: string — 图纸资源 URL
- `options`: DrawingLoadOptions — 加载选项（可选）

**返回值**: Promise\<void\>

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

**示例**:

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

### getLayers()

```typescript
public getLayers(): Drawing2dLayer[]
```

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

**返回值**: Drawing2dLayer[]

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

**示例**:

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

### setLayerVisible()

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

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

**参数**:
- `name`: string — 图层名称
- `visible`: boolean — 是否可见

**示例**:

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

---

## 视图控制

### resetView()

```typescript
public resetView(): void
```

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

### fitToView()

```typescript
public fitToView(): void
```

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

### setZoom()

```typescript
public setZoom(zoom: number): void
```

**功能**: 设置缩放级别

**参数**:
- `zoom`: number — 缩放值

### getZoom()

```typescript
public getZoom(): number
```

**功能**: 获取当前缩放级别

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

---

## 主题

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

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

### offRawEvent()

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

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

---

## 生命周期

### destroy()

```typescript
public destroy(): void
```

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

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

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

---

## 内部架构

```text
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