2026-01-23 16:27:04 +08:00
|
|
|
|
# iflow-engine SDK 快速开始
|
|
|
|
|
|
|
|
|
|
|
|
## 安装
|
|
|
|
|
|
|
|
|
|
|
|
### NPM
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
npm install iflow-engine
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### Yarn
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
yarn add iflow-engine
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PNPM
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
pnpm add iflow-engine
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 基础使用
|
|
|
|
|
|
|
|
|
|
|
|
### 1. 创建 HTML 容器
|
|
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
|
<div id="bim-container" style="width: 100%; height: 100vh;"></div>
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 2. 初始化引擎
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
import { BimEngine } from 'iflow-engine';
|
|
|
|
|
|
|
|
|
|
|
|
// 创建引擎实例
|
|
|
|
|
|
const engine = new BimEngine('bim-container', {
|
|
|
|
|
|
locale: 'zh-CN', // 语言：'zh-CN' | 'en-US'
|
|
|
|
|
|
theme: 'light' // 主题：'light' | 'dark'
|
|
|
|
|
|
});
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 3. 加载模型
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
// 初始化 3D 引擎
|
|
|
|
|
|
engine.engine?.initialize();
|
|
|
|
|
|
|
|
|
|
|
|
// 加载模型
|
|
|
|
|
|
engine.engine?.loadModel('https://example.com/model.gltf', {
|
|
|
|
|
|
autoFit: true // 自动适配视角
|
|
|
|
|
|
});
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 完整示例
|
|
|
|
|
|
|
|
|
|
|
|
### Vue 3
|
|
|
|
|
|
|
|
|
|
|
|
```vue
|
|
|
|
|
|
<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
|
|
|
|
|
|
|
|
|
|
|
|
```tsx
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
|
|
```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>
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 主题切换
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
// 切换到暗色主题
|
|
|
|
|
|
engine.setTheme('dark');
|
|
|
|
|
|
|
|
|
|
|
|
// 切换到亮色主题
|
|
|
|
|
|
engine.setTheme('light');
|
|
|
|
|
|
|
|
|
|
|
|
// 自定义主题
|
|
|
|
|
|
engine.setCustomTheme({
|
|
|
|
|
|
name: 'custom',
|
|
|
|
|
|
primary: '#ff6b6b',
|
|
|
|
|
|
primaryHover: '#ff5252',
|
|
|
|
|
|
primaryActive: '#ff4757',
|
|
|
|
|
|
// ... 其他属性
|
|
|
|
|
|
});
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 语言切换
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
// 切换到英文
|
|
|
|
|
|
engine.setLocale('en-US');
|
|
|
|
|
|
|
|
|
|
|
|
// 切换到中文
|
|
|
|
|
|
engine.setLocale('zh-CN');
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 工具栏操作
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
// 显示/隐藏工具栏
|
|
|
|
|
|
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);
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 测量功能
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
// 显示测量面板
|
|
|
|
|
|
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();
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 剖切功能
|
|
|
|
|
|
|
|
|
|
|
|
### 平面剖切
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
// 显示剖切面板
|
|
|
|
|
|
engine.sectionPlane?.show();
|
|
|
|
|
|
|
|
|
|
|
|
// 隐藏剖切面板
|
|
|
|
|
|
engine.sectionPlane?.hide();
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 轴向剖切
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
// 显示轴向剖切
|
|
|
|
|
|
engine.sectionAxis?.show();
|
|
|
|
|
|
|
|
|
|
|
|
// 设置剖切轴向
|
|
|
|
|
|
engine.sectionAxis?.setActiveAxis('x'); // X 轴
|
|
|
|
|
|
engine.sectionAxis?.setActiveAxis('y'); // Y 轴
|
|
|
|
|
|
engine.sectionAxis?.setActiveAxis('z'); // Z 轴
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 剖切盒
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
// 显示剖切盒
|
|
|
|
|
|
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);
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 漫游功能
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
// 显示漫游控制面板
|
|
|
|
|
|
engine.walkControl?.show();
|
|
|
|
|
|
|
|
|
|
|
|
// 隐藏漫游控制面板
|
|
|
|
|
|
engine.walkControl?.hide();
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 事件监听
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
// 监听模型加载完成
|
|
|
|
|
|
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();
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 销毁引擎
|
|
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
|
// 在组件卸载或页面关闭时销毁
|
|
|
|
|
|
engine.destroy();
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## TypeScript 类型
|
|
|
|
|
|
|
|
|
|
|
|
SDK 提供完整的 TypeScript 类型支持：
|
|
|
|
|
|
|
|
|
|
|
|
```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-28 17:19:36 +08:00
|
|
|
|
- 查看 [架构文档](架构设计.md) 了解设计原理
|
|
|
|
|
|
- 查看 [模块文档](MODULES/模块索引.md) 了解详细 API
|
2026-01-23 16:27:04 +08:00
|
|
|
|
- 查看 [demo](../demo/) 获取更多示例
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
**文档生成时间**: 2026-01-23
|
|
|
|
|
|
**文档版本**: 1.0.0
|
