389 lines
6.9 KiB
Markdown
389 lines
6.9 KiB
Markdown
# 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()`
|
||
- 取消不再需要的事件监听
|
||
|
||
## 下一步
|
||
|
||
- 查看 [架构文档](架构设计.md) 了解设计原理
|
||
- 查看 [模块文档](MODULES/模块索引.md) 了解详细 API
|
||
- 查看 [demo](../demo/) 获取更多示例
|
||
|
||
---
|
||
|
||
**文档生成时间**: 2026-01-23
|
||
**文档版本**: 1.0.0
|