bim_xg/bim_engine

Fork 0

Files

yuding dd4600bb5b 提交代码

2026-03-16 16:13:36 +08:00

16 KiB

Raw Blame History

iflow-engine SDK 快速开始

安装

NPM

npm install iflow-engine

Yarn

yarn add iflow-engine

PNPM

pnpm add iflow-engine

引擎概览

SDK 提供三个独立引擎类，按需引入，互不依赖：

类名	用途	定位
`BimEngine`	3D BIM 模型可视化	完整功能（工具栏、测量、剖切、漫游等 UI 组件）
`BimEngine2d`	2D CAD/DWG 图纸查看	轻量级，无 UI 管理器
`BimEngine720`	720° 全景图查看	轻量级，无 UI 管理器

// ESM 按需导入
import { BimEngine } from 'iflow-engine';       // 3D
import { BimEngine2d } from 'iflow-engine';     // 2D
import { BimEngine720 } from 'iflow-engine';    // 720°

// 也可以一次导入全部
import { BimEngine, BimEngine2d, BimEngine720 } from 'iflow-engine';

<!-- UMD 方式（原生 HTML） -->
<script src="./lib/iflow-engine.umd.js"></script>
<script>
  const { BimEngine, BimEngine2d, BimEngine720 } = IflowEngine;
</script>

注意：三个引擎类共用同一个容器时，需先销毁当前实例再创建新实例。详见多引擎切换。

一、3D 引擎（BimEngine）

完整的 BIM 3D 可视化引擎，包含工具栏、测量、剖切、漫游等全部 UI 功能。

基本用法

import { BimEngine } from 'iflow-engine';

const engine = new BimEngine('container', {
  locale: 'zh-CN',  // 'zh-CN' | 'en-US'
  theme: 'dark'     // 'dark' | 'light'
});

// 初始化 3D 渲染引擎
engine.engine?.initialize({
  backgroundColor: 0x333333,
  showViewCube: true
});

// 加载模型
engine.engine?.loadModel(['https://example.com/model/'], {
  position: [0, 0, 0],
  rotation: [0, 0, 0],
  scale: [1, 1, 1]
});

构造参数

参数	类型	必填	说明
`container`	`HTMLElement \| string`	✅	DOM 元素或元素 ID
`options.locale`	`'zh-CN' \| 'en-US'`		界面语言，默认 `'zh-CN'`
`options.theme`	`'dark' \| 'light'`		主题，默认 `'dark'`

管理器

BimEngine 构造时自动初始化以下管理器：

engine.engine          // EngineManager - 3D 引擎（加载模型、控制渲染）
engine.toolbar         // ToolbarManager - 底部工具栏
engine.buttonGroup     // ButtonGroupManager - 按钮组
engine.dialog          // DialogManager - 弹窗管理
engine.rightKey        // RightKeyManager - 右键菜单
engine.constructTreeBtn // ConstructTreeManagerBtn - 构件树
engine.measure         // MeasureDialogManager - 测量工具
engine.sectionPlane    // SectionPlaneDialogManager - 拾取面剖切
engine.sectionAxis     // SectionAxisDialogManager - 轴向剖切
engine.sectionBox      // SectionBoxDialogManager - 剖切盒
engine.walkControl     // WalkControlManager - 漫游控制
engine.componentDetail // ComponentDetailManager - 构件详情
engine.aiChat          // AiChatManager - AI 对话
engine.setting         // SettingDialogManager - 设置

Vue 3 示例

<template>
  <div ref="containerRef" style="width: 100vw; height: 100vh;" />
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { BimEngine } from 'iflow-engine';

const containerRef = ref<HTMLElement>();
let engine: BimEngine | null = null;

onMounted(() => {
  if (!containerRef.value) return;

  engine = new BimEngine(containerRef.value, {
    locale: 'zh-CN',
    theme: 'dark'
  });

  engine.engine?.initialize({ backgroundColor: 0x333333 });
  engine.engine?.loadModel(['https://example.com/model/']);
});

onUnmounted(() => {
  engine?.destroy();
  engine = null;
});
</script>

React 示例

import { useRef, useEffect } from 'react';
import { BimEngine } from 'iflow-engine';

export function BimViewer() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    const engine = new BimEngine(containerRef.current, {
      locale: 'zh-CN',
      theme: 'dark'
    });

    engine.engine?.initialize({ backgroundColor: 0x333333 });
    engine.engine?.loadModel(['https://example.com/model/']);

    return () => engine.destroy();
  }, []);

  return <div ref={containerRef} style={{ width: '100vw', height: '100vh' }} />;
}

二、2D 图纸引擎（BimEngine2d）

轻量级 2D CAD/DWG 图纸查看引擎，无 UI 管理器，构造时自动初始化。

基本用法

import { BimEngine2d } from 'iflow-engine';

const engine2d = new BimEngine2d('container', {
  locale: 'zh-CN',
  theme: 'dark',
  backgroundColor: 0xf0f0f0,
  gridEnabled: true,
  axesEnabled: true
});

// 加载图纸
await engine2d.loadDrawing('https://example.com/drawing-id');

// 销毁
engine2d.destroy();

构造参数

参数	类型	必填	说明
`container`	`HTMLElement \| string`	✅	DOM 元素或元素 ID
`options.locale`	`'zh-CN' \| 'en-US'`		界面语言
`options.theme`	`'dark' \| 'light'`		主题
`options.backgroundColor`	`number`		背景色，如 `0xffffff`
`options.gridEnabled`	`boolean`		是否显示网格
`options.axesEnabled`	`boolean`		是否显示坐标轴
`options.selectionColor`	`number`		选中构件颜色
`options.highlightColor`	`number`		高亮构件颜色
`options.enablePerformanceMonitoring`	`boolean`		是否启用性能监控

API

// 图纸操作
await engine2d.loadDrawing(url, options?)  // 加载图纸
engine2d.getLayers()                        // 获取所有图层 → Drawing2dLayer[]
engine2d.setLayerVisible(name, visible)    // 设置图层可见性

// 视图控制
engine2d.resetView()                       // 重置视图
engine2d.fitToView()                       // 适应全部内容
engine2d.setZoom(zoom)                     // 设置缩放级别
engine2d.getZoom()                         // 获取当前缩放级别

// 主题
engine2d.setTheme('dark' | 'light')

// 事件
const unsub = engine2d.on('event-name', (payload) => { ... })
unsub()  // 取消订阅
engine2d.onRawEvent(event, handler)        // 底层引擎事件
engine2d.offRawEvent(event, handler)

// 生命周期
engine2d.destroy()                         // 销毁引擎

Vue 3 示例

<template>
  <div ref="containerRef" style="width: 100%; height: 100vh;" />
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { BimEngine2d } from 'iflow-engine';

const containerRef = ref<HTMLElement>();
let engine2d: BimEngine2d | null = null;

onMounted(async () => {
  if (!containerRef.value) return;

  engine2d = new BimEngine2d(containerRef.value, {
    theme: 'light',
    gridEnabled: true
  });

  await engine2d.loadDrawing('https://example.com/drawing-id');
});

onUnmounted(() => {
  engine2d?.destroy();
  engine2d = null;
});
</script>

React 示例

import { useRef, useEffect } from 'react';
import { BimEngine2d } from 'iflow-engine';

export function DrawingViewer() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    const engine2d = new BimEngine2d(containerRef.current, {
      theme: 'light',
      gridEnabled: true
    });

    engine2d.loadDrawing('https://example.com/drawing-id');

    return () => engine2d.destroy();
  }, []);

  return <div ref={containerRef} style={{ width: '100%', height: '100vh' }} />;
}

三、720° 全景引擎（BimEngine720）

轻量级 720° 全景图查看引擎，支持鼠标/触摸旋转和缩放，构造时自动初始化。

基本用法

import { BimEngine720 } from 'iflow-engine';

const engine720 = new BimEngine720('container', {
  fov: 75,
  enableZoom: true,
  enableRotate: true,
  sphereRadius: 500
});

// 加载全景图
await engine720.loadPanorama('https://example.com/panorama.png');

// 销毁
engine720.destroy();

构造参数

参数	类型	必填	说明
`container`	`HTMLElement \| string`	✅	DOM 元素或元素 ID
`options.locale`	`'zh-CN' \| 'en-US'`		界面语言
`options.theme`	`'dark' \| 'light'`		主题
`options.fov`	`number`		视场角，默认 `75`
`options.enableZoom`	`boolean`		是否启用缩放，默认 `true`
`options.enableRotate`	`boolean`		是否启用旋转，默认 `true`
`options.sphereRadius`	`number`		球体半径，默认 `500`
`options.rotateSpeed`	`number`		旋转速度
`options.zoomSpeed`	`number`		缩放速度
`options.enableDamping`	`boolean`		是否启用阻尼（惯性效果）
`options.dampingFactor`	`number`		阻尼因子
`options.minFov`	`number`		最小视场角
`options.maxFov`	`number`		最大视场角

API

// 全景操作
await engine720.loadPanorama(url, options?)     // 加载全景图
await engine720.preloadPanoramas(urls)          // 预加载多个全景图

// 视角控制
engine720.setFov(fov)                           // 设置视场角
engine720.getFov()                              // 获取当前视场角
engine720.lookAt(phi, theta, animated?)         // 设置相机朝向
engine720.resetView()                           // 重置视图

// 主题
engine720.setTheme('dark' | 'light')

// 事件
const unsub = engine720.on('event-name', (payload) => { ... })
unsub()  // 取消订阅
engine720.onRawEvent(event, handler)            // 底层引擎事件
engine720.offRawEvent(event, handler)

// 生命周期
engine720.destroy()                             // 销毁引擎

Vue 3 示例

<template>
  <div ref="containerRef" style="width: 100%; height: 100vh;" />
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { BimEngine720 } from 'iflow-engine';

const containerRef = ref<HTMLElement>();
let engine720: BimEngine720 | null = null;

onMounted(async () => {
  if (!containerRef.value) return;

  engine720 = new BimEngine720(containerRef.value, {
    fov: 75,
    enableZoom: true,
    enableRotate: true,
    sphereRadius: 500
  });

  await engine720.loadPanorama('https://example.com/panorama.png');
});

onUnmounted(() => {
  engine720?.destroy();
  engine720 = null;
});
</script>

React 示例

import { useRef, useEffect } from 'react';
import { BimEngine720 } from 'iflow-engine';

export function PanoramaViewer() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    const engine720 = new BimEngine720(containerRef.current, {
      fov: 75,
      enableZoom: true,
      enableRotate: true,
      sphereRadius: 500
    });

    engine720.loadPanorama('https://example.com/panorama.png');

    return () => engine720.destroy();
  }, []);

  return <div ref={containerRef} style={{ width: '100%', height: '100vh' }} />;
}

多引擎切换

三个引擎类可以共用同一个容器，但同一时刻只能有一个实例。切换时需先销毁当前实例：

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

let current: BimEngine | BimEngine2d | BimEngine720 | null = null;

function destroyCurrent() {
  current?.destroy();
  current = null;
}

// 切换到 3D
function switchTo3D() {
  destroyCurrent();
  const engine = new BimEngine('container', { theme: 'dark' });
  engine.engine?.initialize({ backgroundColor: 0x333333 });
  engine.engine?.loadModel(['https://example.com/model/']);
  current = engine;
}

// 切换到 2D
function switchTo2D() {
  destroyCurrent();
  const engine2d = new BimEngine2d('container', { theme: 'dark' });
  engine2d.loadDrawing('https://example.com/drawing-id');
  current = engine2d;
}

// 切换到 720°
function switchTo720() {
  destroyCurrent();
  const engine720 = new BimEngine720('container', {
    fov: 75,
    enableZoom: true,
    enableRotate: true,
    sphereRadius: 500
  });
  engine720.loadPanorama('https://example.com/panorama.png');
  current = engine720;
}

原生 HTML 完整示例

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>iflow-engine Demo</title>
  <style>
    body { margin: 0; font-family: sans-serif; }
    #container { width: 100vw; height: 100vh; }
    .btn-group { position: fixed; top: 10px; left: 10px; z-index: 100; }
    .btn-group button { padding: 8px 16px; margin-right: 8px; cursor: pointer; }
  </style>
</head>
<body>
  <div class="btn-group">
    <button onclick="switchTo3D()">3D 引擎</button>
    <button onclick="switchTo2D()">2D 图纸</button>
    <button onclick="switchTo720()">720° 全景</button>
  </div>
  <div id="container"></div>

  <script src="./lib/iflow-engine.umd.js"></script>
  <script>
    var BimEngine = IflowEngine.BimEngine;
    var BimEngine2d = IflowEngine.BimEngine2d;
    var BimEngine720 = IflowEngine.BimEngine720;

    var current = null;

    function destroyCurrent() {
      if (current) { current.destroy(); current = null; }
    }

    function switchTo3D() {
      destroyCurrent();
      var engine = new BimEngine('container', { locale: 'zh-CN', theme: 'dark' });
      engine.engine.initialize({ backgroundColor: 0x333333, showViewCube: true });
      engine.engine.loadModel(['https://example.com/model/']);
      current = engine;
    }

    function switchTo2D() {
      destroyCurrent();
      var engine2d = new BimEngine2d('container', { theme: 'dark', gridEnabled: true });
      engine2d.loadDrawing('https://example.com/drawing-id');
      current = engine2d;
    }

    function switchTo720() {
      destroyCurrent();
      var engine720 = new BimEngine720('container', {
        fov: 75, enableZoom: true, enableRotate: true, sphereRadius: 500
      });
      engine720.loadPanorama('https://example.com/panorama.png');
      current = engine720;
    }

    // 默认加载 3D
    switchTo3D();
  </script>
</body>
</html>

TypeScript 类型

SDK 导出所有相关类型，开箱即用：

import type {
  // 3D 引擎
  EngineOptions,
  ModelLoadOptions,

  // 2D 引擎
  Engine2dOptions,
  DrawingLoadOptions,
  Drawing2dLayer,

  // 720 引擎
  Engine720Options,
  PanoramaLoadOptions,
  PanoramaAnnotation,

  // 通用
  ThemeConfig,
  ThemeType,
  EngineEvents,

  // UI 组件（仅 BimEngine 3D 使用）
  DialogOptions,
  DialogPosition,
  ButtonConfig,
  ButtonGroupOptions,
  TreeOptions,
  TreeNodeConfig,
} from 'iflow-engine';

主题与语言

三个引擎类均支持主题切换和语言设置：

// 构造时设置
const engine = new BimEngine('container', { theme: 'dark', locale: 'zh-CN' });
const engine2d = new BimEngine2d('container', { theme: 'light' });
const engine720 = new BimEngine720('container', { theme: 'dark' });

// 运行时切换主题
engine.setTheme('light');
engine2d.setTheme('dark');
engine720.setTheme('light');

// 运行时切换语言（仅 3D 引擎支持）
engine.setLocale('en-US');

// 自定义主题（仅 3D 引擎支持）
engine.setCustomTheme({
  name: 'custom',
  primary: '#1890ff',
  primaryHover: '#40a9ff',
  // ...
});

常见问题

1. 如何只引入需要的引擎？

直接按需 import，构建工具会自动 tree-shaking 未使用的代码：

// 只用 2D，不会打包 3D 和 720 的代码
import { BimEngine2d } from 'iflow-engine';

2. 多个引擎能同时存在吗？

可以，但需要不同的容器。同一个容器同时只能挂载一个引擎实例：

const engine3d = new BimEngine('container-3d', { theme: 'dark' });
const engine2d = new BimEngine2d('container-2d', { theme: 'dark' });
const engine720 = new BimEngine720('container-720', { theme: 'dark' });

3. 切换引擎时页面闪烁

确保先调用 destroy() 再创建新实例。destroy() 会清空容器内容。

4. 模型/图纸加载失败

检查 URL 是否可访问
检查浏览器控制台是否有 CORS 错误
确保使用 HTTP 服务器运行（不能直接打开 HTML 文件）

5. 页面关闭时如何释放资源？

务必调用 destroy() 释放 WebGL 上下文和事件监听：

window.addEventListener('beforeunload', () => {
  engine?.destroy();
});

下一步

架构设计 — 了解 Manager 模式和分层架构
引擎 API 对接 — 底层引擎 API 详细说明
API 调用链 — 调用关系与数据流
demo/ — 完整可运行示例

文档版本: 2.0.0 | 更新日期: 2026-03-10

16 KiB Raw Blame History Unescape Escape

iflow-engine SDK 快速开始

安装

NPM

Yarn

PNPM

引擎概览

一、3D 引擎（BimEngine）

基本用法

构造参数

管理器

Vue 3 示例

React 示例

二、2D 图纸引擎（BimEngine2d）

基本用法

构造参数

API

Vue 3 示例

React 示例

三、720° 全景引擎（BimEngine720）

基本用法

构造参数

API

Vue 3 示例

React 示例

多引擎切换

原生 HTML 完整示例

TypeScript 类型

主题与语言

常见问题

1. 如何只引入需要的引擎？

2. 多个引擎能同时存在吗？

3. 切换引擎时页面闪烁

4. 模型/图纸加载失败

5. 页面关闭时如何释放资源？

下一步

16 KiB

Raw Blame History