图模关联

图模关联是把 2D 图纸中的实体，与已加载 3D 模型中的构件建立业务映射。SDK 负责图纸点击事件和 3D 构件高亮/定位；图纸实体到模型 URL、构件 ID 的映射数据由业务系统维护。

前置条件

• 2D 图纸与目标 3D 模型都已完成初始化和加载。
• 业务系统保存可查询的映射关系：图纸实体 -> 模型 URL + 构件 ID 列表。
• 映射中的 url 必须与 3D Viewer 实际加载时使用的模型 URL 完全一致。

engine2d:entity-clicked 事件会返回底层图纸实体数据，但当前 SDK 未定义稳定的公开字段结构。因此不要假定 data.id、data.handle 等字段一定存在；应由业务系统的映射解析函数处理原始事件数据。

基本流程

用户点击 2D 图纸实体
  -> 监听 engine2d:entity-clicked
  -> 业务系统解析实体并查询映射
  -> 得到模型 URL 与构件 ID
  -> 3D Viewer 高亮或定位构件

示例：点击图纸后高亮 3D 构件

import { BimEngine, BimEngine2d } from 'iflow-engine';

type ModelComponentTarget = {
  url: string;
  ids: number[];
};

const viewer3d = new BimEngine('viewer-3d');
const viewer2d = new BimEngine2d('viewer-2d');

await viewer3d.initialize();
await viewer3d.loadModelByViewToken('MODEL_VIEW_TOKEN');

await viewer2d.ready;
await viewer2d.loadModelByViewToken('DRAWING_VIEW_TOKEN');

async function resolveDrawingEntityLink(
  entityData: unknown
): Promise<ModelComponentTarget | null> {
  // 由业务系统实现：根据 entityData 查询图纸实体与构件的映射。
  // 返回的 url 必须是 3D Viewer 实际加载的模型 URL。
  return null;
}

const off = viewer2d.on('engine2d:entity-clicked', async ({ data }) => {
  const target = await resolveDrawingEntityLink(data);

  if (!target || target.ids.length === 0) {
    console.warn('当前图纸实体没有可用的 3D 构件映射');
    return;
  }

  viewer3d.engine?.highlightModel([target]);
});

// 页面或组件卸载时：
// off();
// viewer2d.destroy();
// viewer3d.destroy();

定位而非高亮

如果业务需要读取目标构件位置，可调用：

const position = viewer3d.engine?.getModelPosition({
  url: target.url,
  ids: target.ids
});

返回为空通常表示模型尚未加载、映射 URL 不一致，或构件 ID 无效。

内置联动模式

3D Viewer 的 activeModelLink3d() / disActiveModelLink3d() 用于开启或关闭引擎内置的 3D 联动模式：

viewer3d.engine?.activeModelLink3d();
// viewer3d.engine?.disActiveModelLink3d();

该模式不负责生成图纸实体与构件的业务映射数据。需要自定义规则时，仍应使用上面的点击事件与业务映射流程。