iflow-engine
v1.1.4
Published
iFlow Engine SDK for Vue2, Vue3, React and HTML
Maintainers
budingsamaReadme
iFlow Engine
一个功能强大的 BIM（建筑信息模型）引擎 SDK，提供 3D 可视化、构件管理、测量工具、剖切功能和漫游控制等完整功能。支持 Vue 2、Vue 3、React 和原生 HTML 等多种前端框架。
✨ 核心特性
- 🎯 框架无关: 支持 Vue 2/3、React 和原生 HTML
- 📦 开箱即用: 提供完整的 BIM 功能组件
- 🎨 主题系统: 内置暗色/亮色主题，支持自定义
- 🌍 国际化: 支持中英文切换
- 📐 测量工具: 标高、距离、角度、坡度、体积等
- ✂️ 剖切功能: 拾取面剖切、轴向剖切、剖切盒
- 🚶 漫游控制: 第一人称漫游、路径漫游、平面图导航
- 🎛️ 组件管理: 树形构件树、属性面板、右键菜单
- 💪 TypeScript: 完整的类型定义支持
📦 安装
npm install iflow-engine或使用 yarn/pnpm:
yarn add iflow-engine
pnpm add iflow-engine🚀 快速开始
在 Vue 3 中使用
<template>
<div ref="containerRef" style="width: 100vw; height: 100vh;"></div>
</template>
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { BimEngine } from 'iflow-engine';
const containerRef = ref<HTMLElement>();
let bimEngine: BimEngine | null = null;
onMounted(() => {
if (containerRef.value) {
// 初始化 BIM 引擎
bimEngine = new BimEngine(containerRef.value, {
locale: 'zh-CN', // 语言: 'zh-CN' | 'en-US'
theme: 'dark' // 主题: 'dark' | 'light'
});
// 初始化各个管理器
bimEngine.initToolbar(); // 底部工具栏
bimEngine.initButtonGroup(); // 按钮组
bimEngine.initDialog(); // 对话框管理器
bimEngine.initEngine(); // 3D 引擎
bimEngine.initRightKey(); // 右键菜单
bimEngine.initConstructTreeBtn(); // 构件树
bimEngine.initPropertyPanel(); // 属性面板
bimEngine.initMeasure(); // 测量工具
bimEngine.initSectionPlane(); // 拾取面剖切
bimEngine.initSectionAxis(); // 轴向剖切
bimEngine.initSectionBox(); // 剖切盒
bimEngine.initWalkControl(); // 漫游控制
bimEngine.initMap(); // 地图
// 加载模型
bimEngine.engine?.loadModel({
url: '/path/to/your/model.ifc',
onProgress: (progress) => {
console.log(`加载进度: ${progress}%`);
},
onComplete: () => {
console.log('模型加载完成');
}
});
}
});
onUnmounted(() => {
bimEngine?.destroy();
});
</script>在 React 中使用
import { useEffect, useRef } from 'react';
import { BimEngine } from 'iflow-engine';
function App() {
const containerRef = useRef<HTMLDivElement>(null);
const bimEngineRef = useRef<BimEngine | null>(null);
useEffect(() => {
if (containerRef.current) {
const bimEngine = new BimEngine(containerRef.current, {
locale: 'zh-CN',
theme: 'dark'
});
// 初始化各个管理器
bimEngine.initToolbar();
bimEngine.initButtonGroup();
bimEngine.initDialog();
bimEngine.initEngine();
bimEngine.initRightKey();
bimEngineRef.current = bimEngine;
return () => {
bimEngine.destroy();
};
}
}, []);
return (
<div
ref={containerRef}
style={{ width: '100vw', height: '100vh' }}
/>
);
}
export default App;在原生 HTML 中使用
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>BIM Engine SDK Demo</title>
<style>
body { margin: 0; padding: 0; }
#container { width: 100vw; height: 100vh; }
</style>
</head>
<body>
<div id="container"></div>
<!-- 使用 UMD 版本 -->
<script src="./node_modules/iflow-engine/dist/iflow-engine.umd.js"></script>
<script>
const container = document.getElementById('container');
const bimEngine = new IflowEngine.BimEngine(container, {
locale: 'zh-CN',
theme: 'dark'
});
// 初始化各个管理器
bimEngine.initToolbar();
bimEngine.initButtonGroup();
bimEngine.initDialog();
bimEngine.initEngine();
</script>
</body>
</html>🏗️ 技术架构
核心设计理念
BIM Engine SDK 采用 管理器模式 (Manager Pattern) 作为核心架构,确保:
- ✅ 组件的生命周期统一管理
- ✅ 避免内存泄漏
- ✅ 简化集成复杂度
- ✅ 支持按需加载
架构分层
┌─────────────────────────────────────────┐
│ BimEngine (主引擎类) │
│ - 生命周期管理 │
│ - 事件系统 │
│ - 主题/国际化 │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Manager 层 (管理器) │
│ - ToolbarManager (工具栏) │
│ - DialogManager (对话框) │
│ - EngineManager (3D引擎) │
│ - MeasureDialogManager (测量) │
│ - SectionPlaneDialogManager (剖切) │
│ - WalkControlManager (漫游) │
│ - ... │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Component 层 (UI组件) │
│ - Dialog (对话框) │
│ - Tree (树形控件) │
│ - ButtonGroup (按钮组) │
│ - MeasurePanel (测量面板) │
│ - SectionPlanePanel (剖切面板) │
│ - ... │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Service 层 (服务) │
│ - LocaleManager (国际化) │
│ - ThemeManager (主题) │
│ - EventEmitter (事件总线) │
└─────────────────────────────────────────┘技术栈
- 语言: TypeScript 5.9.3
- 构建工具: Vite 7.2.6 (Library Mode)
- 类型生成: vite-plugin-dts
- 样式注入: vite-plugin-css-injected-by-js
- 开发环境: Vue 3 (用于 Playground)
📁 项目结构
iflow-engine/
├── src/ # 源代码
│ ├── bim-engine.ts # 主引擎类
│ ├── index.ts # 入口文件
│ ├── managers/ # 管理器层
│ │ ├── toolbar-manager.ts
│ │ ├── dialog-manager.ts
│ │ ├── engine-manager.ts
│ │ ├── measure-dialog-manager.ts
│ │ ├── section-plane-dialog-manager.ts
│ │ ├── section-axis-dialog-manager.ts
│ │ ├── section-box-dialog-manager.ts
│ │ ├── walk-control-manager.ts
│ │ └── ...
│ ├── components/ # UI 组件层
│ │ ├── dialog/ # 对话框组件
│ │ ├── tree/ # 树形控件
│ │ ├── button-group/ # 按钮组
│ │ ├── measure-panel/ # 测量面板
│ │ ├── section-plane-panel/ # 拾取面剖切面板
│ │ ├── section-axis-panel/ # 轴向剖切面板
│ │ ├── section-box-panel/ # 剖切盒面板
│ │ ├── walk-control-panel/ # 漫游控制面板
│ │ └── ...
│ ├── services/ # 服务层
│ │ ├── locale.ts # 国际化服务
│ │ └── theme.ts # 主题服务
│ ├── core/ # 核心模块
│ │ └── event-emitter.ts # 事件系统
│ ├── types/ # 类型定义
│ │ ├── component.ts # 组件接口
│ │ └── events.ts # 事件类型
│ ├── themes/ # 主题配置
│ │ ├── dark.ts # 暗色主题
│ │ └── light.ts # 亮色主题
│ ├── locales/ # 国际化资源
│ │ ├── zh-CN.ts # 简体中文
│ │ └── en-US.ts # 英文
│ ├── utils/ # 工具函数
│ │ └── icon-manager.ts # 图标管理器
│ └── assets/ # 静态资源
├── dist/ # 构建产物
│ ├── iflow-engine.es.js # ESM 格式
│ ├── iflow-engine.umd.js # UMD 格式
│ └── index.d.ts # TypeScript 类型定义
├── demo/ # HTML Demo
├── demo-vue/ # Vue Demo
├── playground/ # 开发调试环境 (Vue 3)
├── docs/ # 文档
│ ├── components/ # 组件文档
│ └── utils/ # 工具文档
├── vite.config.ts # Vite 配置
├── tsconfig.json # TypeScript 配置
└── package.json # 项目配置🎯 核心 API
BimEngine 主类
class BimEngine {
constructor(
container: HTMLElement | string,
options?: {
locale?: 'zh-CN' | 'en-US';
theme?: 'dark' | 'light';
}
);
// 管理器初始化方法
initToolbar(): void;
initButtonGroup(): void;
initDialog(): void;
initEngine(options?: EngineOptions): void;
initRightKey(): void;
initConstructTreeBtn(): void;
initPropertyPanel(): void;
initMeasure(): void;
initSectionPlane(): void;
initSectionAxis(): void;
initSectionBox(): void;
initWalkControl(): void;
initMap(): void;
// 主题和国际化
setTheme(theme: 'dark' | 'light', config?: ThemeConfig): void;
setLocale(locale: 'zh-CN' | 'en-US'): void;
// 事件系统
on(event: string, handler: Function): void;
off(event: string, handler: Function): void;
emit(event: string, ...args: any[]): void;
// 销毁
destroy(): void;
}管理器
每个管理器负责特定功能的生命周期管理:
// 3D 引擎管理器
bimEngine.engine?.loadModel({
url: '/path/to/model.ifc',
onProgress: (progress) => console.log(progress),
onComplete: () => console.log('完成')
});
// 测量工具管理器
bimEngine.measure?.show();
bimEngine.measure?.hide();
// 剖切管理器
bimEngine.sectionPlane?.show();
bimEngine.sectionAxis?.show();
bimEngine.sectionBox?.show();
// 漫游控制管理器
bimEngine.walkControl?.show();
bimEngine.walkControl?.hide();🎨 主题定制
使用内置主题
const bimEngine = new BimEngine(container, {
theme: 'dark' // 'dark' | 'light'
});
// 运行时切换主题
bimEngine.setTheme('light');自定义主题
bimEngine.setTheme('dark', {
primaryColor: '#1890ff',
bgColor: '#1a1a1a',
textColor: '#ffffff',
borderColor: '#333333',
// ... 更多配置
});主题变量
SDK 使用 CSS 变量实现主题系统,所有组件自动响应主题变化:
--bim-primary-color
--bim-bg-color
--bim-text-color
--bim-border-color
--bim-dialog-bg
--bim-dialog-header-bg
--bim-icon-color
/* ... 更多变量 */🌍 国际化
切换语言
const bimEngine = new BimEngine(container, {
locale: 'zh-CN' // 'zh-CN' | 'en-US'
});
// 运行时切换语言
bimEngine.setLocale('en-US');支持的语言
zh-CN: 简体中文en-US: English
🔧 开发指南
环境准备
# 安装依赖
npm install
# 启动开发环境 (Playground)
npm run dev
# 构建 SDK
npm run build
# 运行 HTML Demo
npm run dev:demo
# 运行 Vue Demo
npm run dev:demo-vue构建产物
运行 npm run build 后,会在 dist/ 目录生成:
iflow-engine.es.js- ESM 格式 (用于现代打包工具)iflow-engine.umd.js- UMD 格式 (用于浏览器直接引入)index.d.ts- TypeScript 类型定义*.css- 样式文件 (已内联注入到 JS 中)
package.json 导出配置
{
"main": "./dist/iflow-engine.umd.js",
"module": "./dist/iflow-engine.es.js",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/iflow-engine.es.js",
"require": "./dist/iflow-engine.umd.js"
}
}
}📖 组件文档
详细的组件文档请参考 docs/ 目录:
- Dialog 对话框
- Tree 树形控件
- ButtonGroup 按钮组
- MeasurePanel 测量面板
- SectionPlanePanel 拾取面剖切
- SectionAxisPanel 轴向剖切
- SectionBoxPanel 剖切盒
- WalkControlPanel 漫游控制
- IconManager 图标管理器
🔌 集成示例
Vue 3 + Vite
cd demo-vue
npm install
npm run devHTML
cd demo
npm run dev🤝 贡献指南
欢迎贡献代码!请遵循以下步骤:
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
代码规范
- 使用 TypeScript 编写代码
- 遵循 ESLint 规则
- 编写清晰的注释和文档
- 为新功能添加测试用例
📝 更新日志
v1.0.0 (2024-12-26)
核心功能
- ✨ 初始版本发布
- ✨ 实现管理器模式架构
- ✨ 支持 Vue 2/3、React、HTML
组件系统
- ✨ Dialog 对话框组件
- ✨ Tree 树形控件
- ✨ ButtonGroup 按钮组
- ✨ MeasurePanel 测量面板
- ✨ SectionPlanePanel 拾取面剖切
- ✨ SectionAxisPanel 轴向剖切
- ✨ SectionBoxPanel 剖切盒
- ✨ WalkControlPanel 漫游控制
功能特性
- ✨ 主题系统 (暗色/亮色)
- ✨ 国际化 (中英文)
- ✨ 事件系统
- ✨ 图标管理器
📄 许可证
ISC License
🙏 致谢
感谢所有为本项目做出贡献的开发者!
📮 联系方式
如有问题或建议,请通过以下方式联系:
- 提交 Issue
- 发送邮件至 [email protected]
Made with ❤️ by BIM Engine Team