bim_engine/docs/外部API总览.md

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

1) 获取构件树 getConstructTreeData()

所属模块

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

方法签名

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

入参

• 无入参。

返回值

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

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(...) 未成功）时，返回：

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

调用示例

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

方法签名

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

入参

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

调用示例

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

---

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

所属模块

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

方法签名

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

入参

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

调用示例

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

---

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

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

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

方法签名

fitSectionBoxToModel(): void

调用示例

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

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

---

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

所属模块

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

方法签名

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

入参

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

调用示例

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

---

6) 启动一键编码 startOneClickEncoding()

所属模块

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

方法签名

startOneClickEncoding(): void

入参

• 无入参。

行为约定

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

调用示例

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

方法签名

hasModelCode(): boolean

入参

• 无入参。

返回值

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

行为约定

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

调用示例

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

---

8) 读取缓存编码 readModelCodeFormStoge()

所属模块

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

方法签名

readModelCodeFormStoge(): void

入参

• 无入参。

行为约定

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

调用示例

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 事件。

调用示例

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();