298 lines
5.3 KiB
Markdown
298 lines
5.3 KiB
Markdown
# 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
|