# iflow-engine SDK 快速开始
## 安装
### NPM
```bash
npm install iflow-engine
```
### Yarn
```bash
yarn add iflow-engine
```
### PNPM
```bash
pnpm add iflow-engine
```
## 基础使用
### 1. 创建 HTML 容器
```html
```
### 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
```
### React
```tsx
import { useRef, useEffect } from 'react';
import { BimEngine } from 'iflow-engine';
export function BimViewer() {
const containerRef = useRef(null);
const engineRef = useRef(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 ;
}
```
### 原生 HTML
```html
iflow-engine Demo
```
## 主题切换
```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: '',
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()`
- 取消不再需要的事件监听
## 下一步
- 查看 [架构文档](ARCHITECTURE.md) 了解设计原理
- 查看 [模块文档](MODULES/_INDEX.md) 了解详细 API
- 查看 [demo](../demo/) 获取更多示例
---
**文档生成时间**: 2026-01-23
**文档版本**: 1.0.0