提交代码

docs/ENGINE_2D/API文档.md

@@ -0,0 +1,297 @@
+# 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