# BIM Engine SDK 使用文档 BIM Engine SDK 是一个用于 3D BIM 模型展示的 JavaScript SDK，支持原生 HTML、Vue 2/3 和 React 框架。 ## 目录 - [安装](#安装) - [原生 HTML 使用](#原生-html-使用) - [Vue 3 使用](#vue-3-使用) - [Vue 2 使用](#vue-2-使用) - [React 使用](#react-使用) - [API 参考](#api-参考) - [类型定义](#类型定义) --- ## 安装 ### NPM 安装 ```bash npm install bim-engine-sdk ``` ### CDN / 本地引入 ```html ``` --- ## 原生 HTML 使用 ### 基础示例 ```html BIM Engine Demo
``` ### 完整功能示例 ```html ``` --- ## Vue 3 使用 ### 安装依赖 ```bash npm install bim-engine-sdk ``` ### 组件封装 ```vue ``` ### 使用组件 ```vue ``` --- ## Vue 2 使用 ### 安装依赖 ```bash npm install bim-engine-sdk ``` ### 组件封装 ```vue ``` ### 使用组件 ```vue ``` --- ## React 使用 ### 安装依赖 ```bash npm install bim-engine-sdk ``` ### Hook 封装 ```tsx // hooks/useBimEngine.ts import { useEffect, useRef, useState, useCallback } from 'react'; import { BimEngine } from 'bim-engine-sdk'; import type { EngineOptions, ModelLoadOptions } from 'bim-engine-sdk'; type MeasureMode = 'distance' | 'minDistance' | 'angle' | 'elevation' | 'volume' | 'laserDistance' | 'slope' | 'spaceVolume'; interface UseBimEngineOptions { locale?: 'zh-CN' | 'en-US'; theme?: 'light' | 'dark'; engineOptions?: Omit; onReady?: (engine: BimEngine) => void; onError?: (error: Error) => void; } export function useBimEngine(options: UseBimEngineOptions = {}) { const containerRef = useRef(null); const engineRef = useRef(null); const [isReady, setIsReady] = useState(false); const [error, setError] = useState(null); // 初始化引擎 useEffect(() => { if (!containerRef.current) return; try { // 创建引擎实例 const engine = new BimEngine(containerRef.current, { locale: options.locale || 'zh-CN', theme: options.theme || 'light' }); // 初始化 3D 引擎 const success = engine.engine?.initialize({ version: 'v2', showStats: false, showViewCube: true, ...options.engineOptions }); if (success) { engineRef.current = engine; setIsReady(true); options.onReady?.(engine); } else { throw new Error('3D 引擎初始化失败'); } } catch (err) { const error = err as Error; setError(error); options.onError?.(error); } // 清理 return () => { engineRef.current?.destroy(); engineRef.current = null; setIsReady(false); }; }, []); // 加载模型 const loadModel = useCallback((url: string, modelOptions?: ModelLoadOptions) => { engineRef.current?.engine?.loadModel(url, modelOptions); }, []); // 回到主视角 const goHome = useCallback(() => { engineRef.current?.engine?.CameraGoHome(); }, []); // 激活测量 const activateMeasure = useCallback((mode: MeasureMode) => { engineRef.current?.engine?.activateMeasure(mode); }, []); // 停用测量 const deactivateMeasure = useCallback(() => { engineRef.current?.engine?.deactivateMeasure(); }, []); // 切换主题 const setTheme = useCallback((theme: 'light' | 'dark') => { engineRef.current?.setTheme(theme); }, []); // 切换语言 const setLocale = useCallback((locale: 'zh-CN' | 'en-US') => { engineRef.current?.setLocale(locale); }, []); return { containerRef, engine: engineRef.current, isReady, error, loadModel, goHome, activateMeasure, deactivateMeasure, setTheme, setLocale }; } ``` ### 组件封装 ```tsx // components/BimViewer.tsx import React, { useEffect } from 'react'; import { useBimEngine } from '../hooks/useBimEngine'; import type { ModelLoadOptions } from 'bim-engine-sdk'; interface BimViewerProps { modelUrl?: string; modelOptions?: ModelLoadOptions; locale?: 'zh-CN' | 'en-US'; theme?: 'light' | 'dark'; className?: string; style?: React.CSSProperties; onReady?: (engine: any) => void; onError?: (error: Error) => void; } export const BimViewer = React.forwardRef((props, ref) => { const { modelUrl, modelOptions, locale = 'zh-CN', theme = 'light', className, style, onReady, onError } = props; const { containerRef, engine, isReady, loadModel, goHome, activateMeasure, deactivateMeasure, setTheme, setLocale } = useBimEngine({ locale, theme, onReady, onError }); // 暴露方法给父组件 React.useImperativeHandle(ref, () => ({ getEngine: () => engine, loadModel, goHome, activateMeasure, deactivateMeasure, setTheme, setLocale })); // 加载模型 useEffect(() => { if (isReady && modelUrl) { loadModel(modelUrl, modelOptions); } }, [isReady, modelUrl, modelOptions, loadModel]); return (
); }); BimViewer.displayName = 'BimViewer'; ``` ### 使用组件 ```tsx // App.tsx import React, { useRef } from 'react'; import { BimViewer } from './components/BimViewer'; function App() { const viewerRef = useRef(null); const handleReady = (engine: any) => { console.log('引擎已就绪', engine); }; const handleError = (error: Error) => { console.error('引擎错误', error); }; const goHome = () => { viewerRef.current?.goHome(); }; const measure = (mode: string) => { viewerRef.current?.activateMeasure(mode); }; const stopMeasure = () => { viewerRef.current?.deactivateMeasure(); }; return (
); } export default App; ``` --- ## API 参考 ### BimEngine 主引擎类，用于创建和管理 BIM 引擎实例。 #### 构造函数 ```typescript new BimEngine(container: HTMLElement | string, options?: { locale?: 'zh-CN' | 'en-US'; theme?: 'light' | 'dark'; }) ``` | 参数 | 类型 | 说明 | |------|------|------| | container | HTMLElement \| string | 容器元素或容器 ID | | options.locale | string | 语言设置，默认 'zh-CN' | | options.theme | string | 主题设置，默认 'light' | #### 属性 | 属性 | 类型 | 说明 | |------|------|------| | engine | EngineManager | 3D 引擎管理器 | | toolbar | ToolbarManager | 工具栏管理器 | | dialog | DialogManager | 弹窗管理器 | | measure | MeasureDialogManager | 测量面板管理器 | #### 方法 | 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | setLocale | locale: 'zh-CN' \| 'en-US' | void | 设置语言 | | getLocale | - | string | 获取当前语言 | | setTheme | theme: 'light' \| 'dark' | void | 设置主题 | | setCustomTheme | theme: ThemeConfig | void | 设置自定义主题 | | destroy | - | void | 销毁引擎 | --- ### EngineManager 3D 引擎管理器，通过 `engine.engine` 访问。 #### 方法 | 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | initialize | options?: EngineOptions | boolean | 初始化 3D 引擎 | | isInitialized | - | boolean | 检查是否已初始化 | | loadModel | url: string, options?: ModelLoadOptions | void | 加载模型 | | CameraGoHome | - | void | 回到主视角 | | activateMeasure | mode: MeasureMode | void | 激活测量功能 | | deactivateMeasure | - | void | 停用测量功能 | | getCurrentMeasureType | - | MeasureMode \| null | 获取当前测量类型 | | getEngine | - | any | 获取原始引擎实例 | | destroy | - | void | 销毁引擎 | --- ## 类型定义 ### EngineOptions ```typescript interface EngineOptions { container: HTMLElement; // 容器元素 backgroundColor?: number | string; // 背景色 version?: 'v1' | 'v2'; // WebGL 版本 showStats?: boolean; // 是否显示性能统计 showViewCube?: boolean; // 是否显示视图立方体 } ``` ### ModelLoadOptions ```typescript interface ModelLoadOptions { position?: [number, number, number]; // 位置 [x, y, z] rotation?: [number, number, number]; // 旋转 [x, y, z]（弧度） scale?: [number, number, number]; // 缩放 [x, y, z] id?: string; // 模型 ID } ``` ### MeasureMode ```typescript type MeasureMode = | 'distance' // 距离测量 | 'minDistance' // 最小距离测量 | 'angle' // 角度测量 | 'elevation' // 标高测量 | 'volume' // 体积测量 | 'laserDistance' // 激光测距 | 'slope' // 坡度测量 | 'spaceVolume'; // 空间体积测量 ``` --- ## 注意事项 1. **容器尺寸**：确保容器元素有明确的宽度和高度，否则 3D 引擎可能无法正常渲染。 2. **模型路径**：模型路径应为相对于 HTML 页面的路径，或者完整的 URL。 3. **销毁清理**：在组件卸载或页面关闭前，务必调用 `destroy()` 方法释放资源。 4. **浏览器兼容性**：SDK 需要浏览器支持 WebGL。建议使用现代浏览器（Chrome、Firefox、Safari、Edge）。 5. **静态资源**：确保 Draco 解码器等静态资源正确部署： ``` /static/js/draco/ ├── DRACOLoader.js ├── draco_decoder.js ├── draco_decoder.wasm ├── draco_encoder.js └── draco_wasm_wrapper.js ``` --- ## 常见问题 ### Q: 模型加载失败怎么办？ A: 检查以下几点： - 模型路径是否正确 - 模型格式是否支持 - 网络请求是否正常（F12 查看 Network） - Draco 解码器是否正确部署 ### Q: 如何自定义主题？ A: 使用 `setCustomTheme` 方法： ```javascript engine.setCustomTheme({ background: '#1a1a2e', textPrimary: '#ffffff', textSecondary: '#cccccc', // ... 更多配置 }); ``` ### Q: 如何监听引擎事件？ A: 使用 `on` 方法监听事件： ```javascript engine.on('modelLoaded', (data) => { console.log('模型已加载', data); }); ``` --- ## 技术支持 如有问题，请联系技术支持或提交 Issue。