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
This commit is contained in:
yuding
388
docs/GETTING_STARTED.md
Normal file
388
docs/GETTING_STARTED.md
Normal file
@@ -0,0 +1,388 @@
|
||||
# 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()`
|
||||
- 取消不再需要的事件监听
|
||||
|
||||
## 下一步
|
||||
|
||||
- 查看 [架构文档](ARCHITECTURE.md) 了解设计原理
|
||||
- 查看 [模块文档](MODULES/_INDEX.md) 了解详细 API
|
||||
- 查看 [demo](../demo/) 获取更多示例
|
||||
|
||||
---
|
||||
|
||||
**文档生成时间**: 2026-01-23
|
||||
**文档版本**: 1.0.0
|
||||
Reference in New Issue
Block a user