bim_xg/bim_engine
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
89ae01ffd7e210161468f287d8c5b3df1a160585
bim_engine/docs/GETTING_STARTED.md
yuding 89ae01ffd7 feat: upgrade iflow-engine-base to v1.0.5, add pause/resume rendering API 
- Update iflow-engine-base from 1.0.1 to 1.0.5
- Change default engine version from v1 to v2
- Add pauseRendering() and resumeRendering() methods
- Add switch model feature in demos
- Update model URLs in demos
- Add new documentation files
2026-01-23 16:27:04 +08:00

6.9 KiB
Raw Blame History

iflow-engine SDK 快速开始

安装

NPM

npm install iflow-engine

Yarn

yarn add iflow-engine

PNPM

pnpm add iflow-engine

基础使用

1. 创建 HTML 容器

<div id="bim-container" style="width: 100%; height: 100vh;"></div>

2. 初始化引擎

import { BimEngine } from 'iflow-engine';

// 创建引擎实例
const engine = new BimEngine('bim-container', {
  locale: 'zh-CN',  // 语言：'zh-CN' | 'en-US'
  theme: 'light'    // 主题：'light' | 'dark'
});

3. 加载模型

// 初始化 3D 引擎
engine.engine?.initialize();

// 加载模型
engine.engine?.loadModel('https://example.com/model.gltf', {
  autoFit: true  // 自动适配视角
});

完整示例

Vue 3

<template>
  <div ref="containerRef" class="bim-container"></div>
</template>

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

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

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

    // 初始化 3D 引擎
    engine.engine?.initialize();

    // 加载模型
    engine.engine?.loadModel('/models/building.gltf');
  }
});

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

<style scoped>
.bim-container {
  width: 100%;
  height: 100vh;
}
</style>

React

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

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

  useEffect(() => {
    if (containerRef.current && !engineRef.current) {
      engineRef.current = new BimEngine(containerRef.current, {
        locale: 'zh-CN',
        theme: 'light'
      });

      // 初始化 3D 引擎
      engineRef.current.engine?.initialize();

      // 加载模型
      engineRef.current.engine?.loadModel('/models/building.gltf');
    }

    return () => {
      engineRef.current?.destroy();
      engineRef.current = null;
    };
  }, []);

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

原生 HTML

<!DOCTYPE html>
<html>
<head>
  <title>iflow-engine Demo</title>
  <style>
    #bim-container {
      width: 100%;
      height: 100vh;
    }
  </style>
</head>
<body>
  <div id="bim-container"></div>

  <script type="module">
    import { BimEngine } from './lib/iflow-engine.es.js';

    const engine = new BimEngine('bim-container', {
      locale: 'zh-CN',
      theme: 'light'
    });

    // 初始化 3D 引擎
    engine.engine?.initialize();

    // 加载模型
    engine.engine?.loadModel('./models/building.gltf');
  </script>
</body>
</html>

主题切换

// 切换到暗色主题
engine.setTheme('dark');

// 切换到亮色主题
engine.setTheme('light');

// 自定义主题
engine.setCustomTheme({
  name: 'custom',
  primary: '#ff6b6b',
  primaryHover: '#ff5252',
  primaryActive: '#ff4757',
  // ... 其他属性
});

语言切换

// 切换到英文
engine.setLocale('en-US');

// 切换到中文
engine.setLocale('zh-CN');

工具栏操作

// 显示/隐藏工具栏
engine.toolbar?.show();
engine.toolbar?.hide();

// 添加自定义按钮
engine.toolbar?.addButton({
  id: 'custom-btn',
  type: 'button',
  label: '自定义',
  icon: '<svg>...</svg>',
  onClick: () => {
    console.log('Custom button clicked');
  }
});

// 设置按钮激活状态
engine.toolbar?.setBtnActive('measure', true);

测量功能

// 显示测量面板
engine.measure?.show();

// 切换测量模式
engine.measure?.switchMode('distance');     // 距离
engine.measure?.switchMode('angle');        // 角度
engine.measure?.switchMode('volume');       // 体积
engine.measure?.switchMode('elevation');    // 标高
engine.measure?.switchMode('slope');        // 坡度

// 获取测量配置
const config = engine.measure?.getConfig();
console.log(config); // { unit: 'mm', precision: 2 }

// 设置测量配置
engine.measure?.setConfig({ unit: 'cm', precision: 1 });

// 清除所有测量结果
engine.measure?.clearAll();

剖切功能

平面剖切

// 显示剖切面板
engine.sectionPlane?.show();

// 隐藏剖切面板
engine.sectionPlane?.hide();

轴向剖切

// 显示轴向剖切
engine.sectionAxis?.show();

// 设置剖切轴向
engine.sectionAxis?.setActiveAxis('x');  // X 轴
engine.sectionAxis?.setActiveAxis('y');  // Y 轴
engine.sectionAxis?.setActiveAxis('z');  // Z 轴

剖切盒

// 显示剖切盒
engine.sectionBox?.show();

// 获取剖切范围
const range = engine.sectionBox?.getRange();
console.log(range); // { minX, maxX, minY, maxY, minZ, maxZ }

// 设置剖切范围
engine.sectionBox?.setRange({ minX: 0, maxX: 100 });

// 反向剖切
engine.sectionBox?.setReversedState(true);

漫游功能

// 显示漫游控制面板
engine.walkControl?.show();

// 隐藏漫游控制面板
engine.walkControl?.hide();

事件监听

// 监听模型加载完成
const unsubscribe = engine.on('engine:model-loaded', (payload) => {
  console.log('Model loaded:', payload.url);
});

// 监听对象点击
engine.on('engine:object-clicked', (payload) => {
  console.log('Object clicked:', payload.objectId, payload.position);
});

// 监听主题变更
engine.on('sys:theme-changed', (payload) => {
  console.log('Theme changed:', payload.theme);
});

// 取消监听
unsubscribe();

销毁引擎

// 在组件卸载或页面关闭时销毁
engine.destroy();

TypeScript 类型

SDK 提供完整的 TypeScript 类型支持：

import type {
  // 主入口
  BimEngine,

  // 配置类型
  EngineOptions,
  ModelLoadOptions,
  DialogOptions,
  DialogPosition,
  ButtonConfig,
  ButtonGroupOptions,
  TreeOptions,
  TreeNodeConfig,
  TreeNodeCheckState,
  CollapseOptions,
  CollapseItemConfig,
  DescriptionOptions,
  DescriptionItem,

  // 主题类型
  ThemeConfig,
  ThemeType,

  // 事件类型
  EngineEvents,
} from 'iflow-engine';

常见问题

1. 模型加载失败

  • 检查模型 URL 是否正确
  • 确保模型格式受支持（GLTF/GLB/IFC）
  • 检查 CORS 配置

2. 工具栏不显示

  • 确保容器有足够的尺寸
  • 检查是否调用了 engine.initialize()

3. 主题不生效

  • 确保在引擎初始化后再设置主题
  • 检查自定义主题配置是否完整

4. 内存泄漏

  • 确保在组件卸载时调用 engine.destroy()
  • 取消不再需要的事件监听

下一步

文档生成时间: 2026-01-23 文档版本: 1.0.0