# iFlow Engine

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

[![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-blue.svg)](https://www.typescriptlang.org/)
[![Vite](https://img.shields.io/badge/Vite-7.2.6-646CFF.svg)](https://vitejs.dev/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## ✨ 核心特性

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

## 📦 安装

```bash
npm install iflow-engine
```

或使用 yarn/pnpm:

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

## 🚀 快速开始

### 在 Vue 3 中使用

```vue
<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' | 'zh-TW' | 'en-US'
      theme: 'dark',    // 主题: 'dark' | 'light'
      enableRadialToolbar: true,
      enableConstructTree: true,
      enableRightKeyMenu: true,
      showModelInfoStats: true
    });

    // BimEngine 构造时会自动组装 UI/Manager；3D 渲染底层需要显式初始化
    bimEngine.engine?.initialize({
      backgroundColor: 0x333333,
      showViewCube: true
    });

    // 加载模型（EngineManager 对外公共 API）
    bimEngine.engine?.loadModel(
      ['/path/to/your/model.ifc'],
      {
        onProgress: (progress) => {
          console.log(`加载进度: ${progress}%`);
        },
        onComplete: () => {
          console.log('模型加载完成');
        }
      }
    );
  }
});

onUnmounted(() => {
  bimEngine?.destroy();
});
</script>
```

### 在 React 中使用

```tsx
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.engine?.initialize({ backgroundColor: 0x333333 });

      bimEngineRef.current = bimEngine;

      return () => {
        bimEngine.destroy();
      };
    }
  }, []);

  return (
    <div
      ref={containerRef}
      style={{ width: '100vw', height: '100vh' }}
    />
  );
}

export default App;
```

### 在原生 HTML 中使用

```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'
    });

    // 初始化 3D 渲染底层
    bimEngine.engine?.initialize({ backgroundColor: 0x333333 });
  </script>
</body>
</html>
```

## 🏗️ 技术架构

### 核心设计理念

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

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

> 架构更新（2026-03）
>
> - `EngineManager` 已从全量透传层收敛为“外部公共 API + 生命周期编排”
> - 内部 Manager 统一通过 `BaseManager.engineComponent` 直接访问 `Engine` 组件
> - 非 Manager 场景通过 `registry.engine3d?.getEngineComponent()?.xxx()` 访问引擎能力
> - `Engine.getEngine()` 已移除，事件订阅使用 `onRawEvent()/offRawEvent()`

### 架构分层

```
┌─────────────────────────────────────────┐
│         BimEngine (主引擎类)             │
│  - 生命周期管理                          │
│  - 事件系统                              │
│  - 主题/国际化                           │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│          Manager 层 (管理器)             │
│  - RadialToolbarManager (径向工具栏)      │
│  - DialogManager (对话框)                │
│  - EngineManager (外部公共API/生命周期)    │
│  - MeasureDialogManager (测量)           │
│  - SectionPlaneDialogManager (剖切)      │
│  - WalkDockManager (漫游/小地图 Dock)     │
│  - ...                                   │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│        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/                 # 管理器层
│   │   ├── radial-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-dock-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';
      enableRadialToolbar?: boolean;
      enableConstructTree?: boolean;
      enableRightKeyMenu?: boolean;
      showModelInfoStats?: boolean;
    }
  );

  // BimEngine 构造时自动组装 UI/Manager；3D 渲染底层通过 engine 初始化
  engine: EngineManager | null;
  radialToolbar: RadialToolbarManager | null;
  bottomDock: BottomDockManager | null;
  measureDock: MeasureDockManager | null;
  sectionDock: SectionDockManager | null;
  walkDock: WalkDockManager | null;
  componentTreeDrawer: ComponentTreeDrawerManager | null;
  setting: SettingDialogManager | null;

  // 主题和国际化
  setTheme(theme: 'dark' | 'light'): void;
  setCustomTheme(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;
}
```

其中：

- `enableRadialToolbar` 控制是否创建径向工具栏，默认 `true`
- `enableConstructTree` 同时控制 `constructTreeBtn` 和 `componentTreeDrawer`，默认 `true`
- `enableRightKeyMenu` 控制是否创建右键菜单，默认 `true`
- `showModelInfoStats` 控制左下角模型信息（构件数 / 三角面 / 顶点数），默认 `true`

这些参数属于 `BimEngine` 构造阶段的 UI 组装配置；`bimEngine.engine?.initialize(...)` 中的 `showStats` 仍然只控制底层 3D 引擎的性能统计显示。

### 管理器

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

```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/` 目录:

- [模块索引](docs/MODULES/模块索引.md)
- [组件模块](docs/MODULES/组件模块.md)
- [管理器模块](docs/MODULES/管理器模块.md)
- [设置系统](docs/MODULES/设置系统.md)
- [外部 API 总览](docs/外部API总览.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 漫游控制

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

## 📄 许可证

MIT License

## 🙏 致谢

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

## 📮 联系方式

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

- 提交 [Issue](https://github.com/your-repo/iflow-engine/issues)
- 发送邮件至 your-email@example.com

---

**Made with ❤️ by BIM Engine Team**
