BIM Engine SDK Demo

); } export default App; ``` ### 在原生 HTML 中使用 ```html BIM Engine SDK Demo

``` ## 🏗️ 技术架构 ### 核心设计理念 BIM Engine SDK 采用 **管理器模式 (Manager Pattern)** 作为核心架构,确保: - ✅ 组件的生命周期统一管理 - ✅ 避免内存泄漏 - ✅ 简化集成复杂度 - ✅ 支持按需加载 > 架构更新（2026-03） > > - `EngineManager` 已从全量透传层收敛为“外部公共 API + 生命周期编排” > - 内部 Manager 统一通过 `BaseManager.engineComponent` 直接访问 `Engine` 组件 > - 非 Manager 场景通过 `registry.engine3d?.getEngineComponent()?.xxx()` 访问引擎能力 > - `Engine.getEngine()` 已移除，事件订阅使用 `onRawEvent()/offRawEvent()` ### 架构分层 ``` ┌─────────────────────────────────────────┐ │ BimEngine (主引擎类) │ │ - 生命周期管理 │ │ - 事件系统 │ │ - 主题/国际化 │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ Manager 层 (管理器) │ │ - ToolbarManager (工具栏) │ │ - DialogManager (对话框) │ │ - EngineManager (外部公共API/生命周期) │ │ - 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 主类 ```typescript class BimEngine { constructor( container: HTMLElement | string, options?: { locale?: 'zh-CN' | 'zh-TW' | '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' | 'zh-TW' | 'en-US'): void; // 事件系统 on(event: string, handler: Function): void; off(event: string, handler: Function): void; emit(event: string, ...args: any[]): void; // 销毁 destroy(): void; } ``` ### 管理器每个管理器负责特定功能的生命周期管理: ```typescript // 3D 引擎管理器（对外公共 API） bimEngine.engine?.loadModel( ['/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(); ``` ## 🎨 主题定制 ### 使用内置主题 ```typescript const bimEngine = new BimEngine(container, { theme: 'dark' // 'dark' | 'light' }); // 运行时切换主题 bimEngine.setTheme('light'); ``` ### 自定义主题 ```typescript bimEngine.setTheme('dark', { primaryColor: '#1890ff', bgColor: '#1a1a1a', textColor: '#ffffff', borderColor: '#333333', // ... 更多配置 }); ``` ### 主题变量 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 /* ... 更多变量 */ ``` ## 🌍 国际化 ### 切换语言 ```typescript const bimEngine = new BimEngine(container, { locale: 'zh-CN' // 'zh-CN' | 'zh-TW' | 'en-US' }); // 运行时切换语言 bimEngine.setLocale('en-US'); ``` ### 支持的语言 - `zh-CN`: 简体中文 - `zh-TW`: 繁体中文 - `en-US`: English ## 🔧 开发指南 ### 环境准备 ```bash # 安装依赖 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 导出配置 ```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 对话框](docs/components/dialog.md) - [Tree 树形控件](docs/components/tree.md) - [ButtonGroup 按钮组](docs/components/button-group.md) - [MeasurePanel 测量面板](docs/components/measure-panel.md) - [SectionPlanePanel 拾取面剖切](docs/components/section-plane-panel.md) - [SectionAxisPanel 轴向剖切](docs/components/section-axis-panel.md) - [SectionBoxPanel 剖切盒](docs/components/section-box-panel.md) - [WalkControlPanel 漫游控制](docs/components/walk-control-panel.md) - [IconManager 图标管理器](docs/utils/icon-manager.md) ## 🔌 集成示例 ### Vue 3 + Vite ```bash cd demo-vue npm install npm run dev ``` ### HTML ```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 ### 代码规范 - 使用 TypeScript 编写代码 - 遵循 ESLint 规则 - 编写清晰的注释和文档 - 为新功能添加测试用例 ## 📝 更新日志 ### v1.3.2 (2026-03-05) **架构优化** - ✨ EngineManager 瘦身：移除大规模 1:1 透传方法 - ✨ 新增 `EngineManager.getEngineComponent()` 供内部访问 - ✨ BaseManager 新增 `engineComponent` 便捷访问器 - ✨ Manager 内部调用统一迁移为 `this.engineComponent?.xxx()` - ✨ 原始事件访问改为 `onRawEvent()/offRawEvent()`，移除 `getEngine()` ### v1.0.0 (2024-12-26) **核心功能** - ✨ 初始版本发布 - ✨ 实现管理器模式架构 - ✨ 支持 Vue 2/3、React、HTML **组件系统** - ✨ Dialog 对话框组件 - ✨ Tree 树形控件 - ✨ ButtonGroup 按钮组 - ✨ MeasurePanel 测量面板 - ✨ SectionPlanePanel 拾取面剖切 - ✨ SectionAxisPanel 轴向剖切 - ✨ SectionBoxPanel 剖切盒 - ✨ WalkControlPanel 漫游控制 **功能特性** - ✨ 主题系统 (暗色/亮色) - ✨ 国际化 (中英文) - ✨ 事件系统 - ✨ 图标管理器 ## 📄 许可证 ISC License ## 🙏 致谢感谢所有为本项目做出贡献的开发者! ## 📮 联系方式如有问题或建议,请通过以下方式联系: - 提交 [Issue](https://github.com/your-repo/iflow-engine/issues) - 发送邮件至 your-email@example.com --- **Made with ❤️ by BIM Engine Team**