bim_engine/docs/外部API总览.md

# iflow-engine 外部 API（第三方接入）

## 1) 获取构件树 `getConstructTreeData()`

### 所属模块

- 调用入口：`bimEngine.engine`
- 源码位置：`src/managers/engine-manager.ts`

### 方法签名

```ts
getConstructTreeData(): {
  level: EngineModelData[];
  type: EngineModelData[];
  major: EngineModelData[];
}
```

### 入参

- 无入参。

### 返回值

- 返回一个对象，包含三类构件树：
  - `level`: 楼层树
  - `type`: 类型树
  - `major`: 专业树

```ts
type EngineTreeNode = {
  name?: string;
  id?: string | null;
  ids?: string[] | null;
  children?: EngineTreeNode[] | null;
  isLeaf?: boolean;
};

type EngineModelData = {
  name?: string;
  url: string;
  children?: EngineTreeNode[] | null;
};
```

### 行为约定

- 当 3D 引擎未初始化（`engine.initialize(...)` 未成功）时，返回：

```ts
{ level: [], type: [], major: [] }
```

### 调用示例

```ts
const treeData = bimEngine.engine?.getConstructTreeData();

if (treeData) {
  console.log('level tree:', treeData.level);
  console.log('type tree:', treeData.type);
  console.log('major tree:', treeData.major);
}
```

---

## 2) 获取构件信息 `getComponentProperties(url, id, callback)`

### 所属模块

- 调用入口：`bimEngine.engine`
- 源码位置：`src/managers/engine-manager.ts`

### 方法签名

```ts
getComponentProperties(url: string, id: string, callback: (data: any) => void): void
```

### 入参

- `url: string`：构件所属模型 URL
- `id: string`：构件 ID
- `callback: (data: any) => void`：异步回调，返回构件属性

### 调用示例

```ts
bimEngine.engine?.getComponentProperties(modelUrl, componentId, (data) => {
  console.log('component properties:', data);
});
```

---

## 3) 高亮指定构件 `highlightModel(models)`

### 所属模块

- 调用入口：`bimEngine.engine?.getEngineComponent()`
- 源码位置：`src/components/engine/index.ts`

### 方法签名

```ts
highlightModel(models: { url: string; ids: number[] }[]): void
```

### 入参

- `models`：构件列表（可批量）
  - `url: string`：模型 URL
  - `ids: number[]`：要高亮的构件 ID 数组

### 调用示例

```ts
bimEngine.engine?.getEngineComponent()?.highlightModel([
  { url: modelUrl, ids: [350518] }
]);
```

---

## 4) 剖切指定构件（推荐流程）

当前引擎提供的是“剖切盒适配已高亮构件”的能力，推荐按两步调用：

1. 先高亮目标构件：`highlightModel(...)`
2. 再执行剖切盒适配：`fitSectionBoxToModel()`

### 方法签名

```ts
fitSectionBoxToModel(): void
```

### 调用示例

```ts
const engineComp = bimEngine.engine?.getEngineComponent();

engineComp?.highlightModel([{ url: modelUrl, ids: [350518] }]);
engineComp?.fitSectionBoxToModel();
```

---

## 5) 隐藏其他构件 `isolateModels(models)`

### 所属模块

- 调用入口：`bimEngine.engine?.getEngineComponent()`
- 源码位置：`src/components/engine/index.ts`

### 方法签名

```ts
isolateModels(models: { url: string; ids: number[] }[]): void
```

### 入参

- `models`：要保留显示的构件（其他构件将隐藏）

### 调用示例

```ts
bimEngine.engine?.getEngineComponent()?.isolateModels([
  { url: modelUrl, ids: [350518] }
]);
```

---

## 6) 启动一键编码 `startOneClickEncoding()`

### 所属模块

- 调用入口：`bimEngine.engine?.getEngineComponent()`
- 源码位置：`src/components/engine/index.ts`

### 方法签名

```ts
startOneClickEncoding(): void
```

### 入参

- 无入参。

### 行为约定

- 调用前建议先订阅 `encoding:start`、`encoding:complete`、`encoding:error` 事件以获取编码进度和结果。
- 若引擎未初始化或底层 `oneClickEncoding` 模块不可用，会在控制台输出警告并静默返回。
- 多次调用将重复触发编码流程（底层行为由 `iflow-engine-base` 决定）。

### 调用示例

```ts
const engineComp = bimEngine.engine?.getEngineComponent();

// 订阅编码事件
bimEngine.on('encoding:start', (data) => {
  console.log('编码开始', data);
});
bimEngine.on('encoding:complete', (data) => {
  console.log('编码完成', data);
});
bimEngine.on('encoding:error', (data) => {
  console.log('编码失败', data);
});

// 启动编码
engineComp?.startOneClickEncoding();
```

---

## 7) 检查模型编码 `hasModelCode()`

### 所属模块

- 调用入口：`bimEngine.engine?.getEngineComponent()`
- 源码位置：`src/components/engine/index.ts`

### 方法签名

```ts
hasModelCode(): boolean
```

### 入参

- 无入参。

### 返回值

- `true`：所有已加载模型均已存在编码数据。
- `false`：至少有一个模型没有编码数据，或引擎未初始化、`oneClickEncoding` 模块不可用。

### 行为约定

- 遍历当前 `engine.models` 数组，对每个模型调用底层 `oneClickEncoding.exitModelCode(url)`。
- 仅当所有模型的返回值为 `true` 时，才返回 `true`。
- 若当前没有加载任何模型，返回 `false`。

### 调用示例

```ts
const hasCode = bimEngine.engine?.getEngineComponent()?.hasModelCode();
console.log('模型是否已编码:', hasCode);
```

---

## 8) 读取缓存编码 `readModelCodeFormStoge()`

### 所属模块

- 调用入口：`bimEngine.engine?.getEngineComponent()`
- 源码位置：`src/components/engine/index.ts`

### 方法签名

```ts
readModelCodeFormStoge(): void
```

### 入参

- 无入参。

### 行为约定

- 遍历当前 `engine.models` 数组，对每个模型调用底层 `oneClickEncoding.readModelCodeFormStoge(url)`。
- 若引擎未初始化或底层模块不可用，会在控制台输出警告并静默返回。
- 无返回值，仅触发读取动作。

### 调用示例

```ts
bimEngine.engine?.getEngineComponent()?.readModelCodeFormStoge();
```

---

## 9) 一键编码事件

### 所属模块

- 事件总线：`bimEngine`（通过 `ManagerRegistry` 桥接）
- 源码位置：`src/components/engine/index.ts`

### 事件列表

| 事件名 | 触发时机 | payload |
|--------|---------|---------|
| `encoding:start` | 编码流程开始时 | `{ data?: any }` |
| `encoding:complete` | 编码流程成功完成时 | `{ data?: any }` |
| `encoding:error` | 编码流程失败时 | `{ data?: any }` |

### 行为约定

- 事件由底层 `oneClickEncoding` 模块触发，经 `Engine` 组件桥接后冒泡到 `bimEngine` 事件总线。
- 订阅方式与 SDK 其他事件一致：使用 `bimEngine.on(event, handler)`，返回的函数可用于取消订阅。
- 建议在调用 `startOneClickEncoding()` 之前完成事件订阅，避免漏掉 `encoding:start` 事件。

### 调用示例

```ts
const unsubStart = bimEngine.on('encoding:start', (data) => {
  console.log('编码开始', data);
});

const unsubComplete = bimEngine.on('encoding:complete', (data) => {
  console.log('编码完成', data);
});

const unsubError = bimEngine.on('encoding:error', (data) => {
  console.log('编码失败', data);
});

// 启动编码
bimEngine.engine?.getEngineComponent()?.startOneClickEncoding();

// 需要时取消订阅
// unsubStart();
// unsubComplete();
// unsubError();
```