iFlow Engine

> 一个功能强大的 BIM（建筑信息模型）引擎 SDK，提供 3D 可视化、构件管理、测量工具、剖切功能和漫游控制等完整功能。支持 Vue 2、Vue 3、React 和原生 HTML 等多种前端框架。

![TypeScript](https://www.typescriptlang.org/)
![Vite](https://vitejs.dev/)
![License](LICENSE)

✨ 核心特性

- 🎯 框架无关: 支持 Vue 2/3、React 和原生 HTML
- 📦 开箱即用: 提供完整的 BIM 功能组件
- 🎨 主题系统: 内置暗色/亮色主题，支持自定义
- 🌍 国际化: 支持中英文切换
- 📐 测量工具: 标高、距离、角度、坡度、体积等
- ✂️ 剖切功能: 拾取面剖切、轴向剖切、剖切盒
- 🚶 漫游控制: 第一人称漫游、路径漫游、平面图导航
- 🎛️ 组件管理: 树形构件树、属性面板、右键菜单
- 💪 TypeScript: 完整的类型定义支持

📦 安装

``bash npm install iflow-engine`

或使用 yarn/pnpm:

`bash yarn add iflow-engine pnpm add iflow-engine`

`🚀 快速开始`

`$3`

`vue

`$3`

`tsx import { useEffect, useRef } from 'react'; import { BimEngine } from 'iflow-engine';

function App() { const containerRef = useRef(null); const bimEngineRef = useRef(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 ( ref={containerRef} style={{ width: '100vw', height: '100vh' }} /> ); }

export default App;`

`$3`

`html BIM Engine SDK Demo

`🏗️ 技术架构`

`$3`

BIM Engine SDK 采用管理器模式 (Manager Pattern) 作为核心架构,确保:

- ✅ 组件的生命周期统一管理 - ✅ 避免内存泄漏 - ✅ 简化集成复杂度 - ✅ 支持按需加载

`$3`

`┌─────────────────────────────────────────┐ │ BimEngine (主引擎类) │ │ - 生命周期管理 │ │ - 事件系统 │ │ - 主题/国际化 │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ Manager 层 (管理器) │ │ - ToolbarManager (工具栏) │ │ - DialogManager (对话框) │ │ - EngineManager (3D引擎) │ │ - MeasureDialogManager (测量) │ │ - SectionPlaneDialogManager (剖切) │ │ - WalkControlManager (漫游) │ │ - ... │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ Component 层 (UI组件) │ │ - Dialog (对话框) │ │ - Tree (树形控件) │ │ - ButtonGroup (按钮组) │ │ - MeasurePanel (测量面板) │ │ - SectionPlanePanel (剖切面板) │ │ - ... │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ Service 层 (服务) │ │ - LocaleManager (国际化) │ │ - ThemeManager (主题) │ │ - EventEmitter (事件总线) │ └─────────────────────────────────────────┘`

`$3`

- 语言: 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`

`$3`

`typescript 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; }`

`$3`

每个管理器负责特定功能的生命周期管理:

`typescript // 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();`

`🎨 主题定制`

`$3`

`typescript const bimEngine = new BimEngine(container, { theme: 'dark' // 'dark' | 'light' });

// 运行时切换主题 bimEngine.setTheme('light');`

`$3`

`typescript bimEngine.setTheme('dark', { primaryColor: '#1890ff', bgColor: '#1a1a1a', textColor: '#ffffff', borderColor: '#333333', // ... 更多配置 });`

`$3`

SDK 使用 CSS 变量实现主题系统,所有组件自动响应主题变化:

`css --bim-primary-color --bim-bg-color --bim-text-color --bim-border-color --bim-dialog-bg --bim-dialog-header-bg --bim-icon-color / ... 更多变量 /`

`🌍 国际化`

`$3`

`typescript const bimEngine = new BimEngine(container, { locale: 'zh-CN' // 'zh-CN' | 'en-US' });

// 运行时切换语言 bimEngine.setLocale('en-US');`

`$3`

- zh-CN: 简体中文 -en-US: English

`🔧 开发指南`

`$3`

`bash

`安装依赖`


npm install
启动开发环境 (Playground)

npm run dev
构建 SDK

npm run build
运行 HTML Demo

npm run dev:demo
运行 Vue Demo

npm run dev:demo-vue

$3

运行 npm run build 后,会在 dist/ 目录生成:

- iflow-engine.es.js- ESM 格式 (用于现代打包工具) -iflow-engine.umd.js- UMD 格式 (用于浏览器直接引入) -index.d.ts- TypeScript 类型定义 -*.css - 样式文件 (已内联注入到 JS 中)

`$3`

`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 图标管理器

`🔌 集成示例`

`$3`

`bash cd demo-vue npm install npm run dev`

`$3`

`bash cd demo npm run dev`

`🤝 贡献指南`

欢迎贡献代码!请遵循以下步骤:

1. Fork 本仓库 2. 创建特性分支 (git checkout -b feature/AmazingFeature) 3. 提交更改 (git commit -m 'Add some AmazingFeature') 4. 推送到分支 (git push origin feature/AmazingFeature`)
5. 开启 Pull Request

$3

- 使用 TypeScript 编写代码
- 遵循 ESLint 规则
- 编写清晰的注释和文档
- 为新功能添加测试用例

📝 更新日志

$3

核心功能
- ✨ 初始版本发布
- ✨ 实现管理器模式架构
- ✨ 支持 Vue 2/3、React、HTML

组件系统
- ✨ Dialog 对话框组件
- ✨ Tree 树形控件
- ✨ ButtonGroup 按钮组
- ✨ MeasurePanel 测量面板
- ✨ SectionPlanePanel 拾取面剖切
- ✨ SectionAxisPanel 轴向剖切
- ✨ SectionBoxPanel 剖切盒
- ✨ WalkControlPanel 漫游控制

功能特性
- ✨ 主题系统 (暗色/亮色)
- ✨ 国际化 (中英文)
- ✨ 事件系统
- ✨ 图标管理器

📄 许可证

ISC License

🙏 致谢

感谢所有为本项目做出贡献的开发者!

📮 联系方式

如有问题或建议,请通过以下方式联系:

- 提交 Issue
- 发送邮件至 your-email@example.com

---

Made with ❤️ by BIM Engine Team