# 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 @fishdingding/bim-engine-sdk ``` ### Yarn 安装 ```bash yarn add @fishdingding/bim-engine-sdk ``` ### PNPM 安装 ```bash pnpm add @fishdingding/bim-engine-sdk ``` ### CDN / 本地文件引入 如果不使用包管理器，可以直接下载 JS 文件引入： ```html ``` --- ## 原生 HTML 使用 ### 方式一：使用 NPM + 构建工具 ```html BIM Engine Demo
``` ### 方式二：使用 UMD（无构建工具） ```html BIM Engine Demo
``` ### 完整功能示例 ```javascript let engine = null; // 初始化 function init() { engine = new LyzBimEngineSDK.BimEngine('app', { locale: 'zh-CN', theme: 'light' }); engine.engine.initialize({ version: 'v2', showStats: false, showViewCube: true }); engine.engine.loadModel('./model/building'); } // 回到主视角 function goHome() { engine.engine.CameraGoHome(); } // 激活测量功能 // mode: 'distance' | 'minDistance' | 'angle' | 'elevation' | 'volume' | 'laserDistance' | 'slope' | 'spaceVolume' function activateMeasure(mode) { engine.engine.activateMeasure(mode); } // 停用测量 function deactivateMeasure() { engine.engine.deactivateMeasure(); } // 切换主题 function setTheme(theme) { engine.setTheme(theme); // 'light' | 'dark' } // 切换语言 function setLocale(locale) { engine.setLocale(locale); // 'zh-CN' | 'en-US' } // 销毁 function destroy() { engine.destroy(); } window.onload = init; ``` --- ## Vue 3 使用 ### 1. 安装 ```bash npm install @fishdingding/bim-engine-sdk ``` ### 2. 组件封装 ```vue ``` ### 3. 使用组件 ```vue ``` --- ## Vue 2 使用 ### 1. 安装 ```bash npm install @fishdingding/bim-engine-sdk ``` ### 2. 组件封装 ```vue ``` ### 3. 使用组件 ```vue ``` --- ## React 使用 ### 1. 安装 ```bash npm install @fishdingding/bim-engine-sdk ``` ### 2. Hook 封装 ```jsx // hooks/useBimEngine.js import { useEffect, useRef, useState, useCallback } from 'react'; import { BimEngine } from '@fishdingding/bim-engine-sdk'; export function useBimEngine(options = {}) { 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' }); 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) { setError(err); options.onError?.(err); } return () => { engineRef.current?.destroy(); engineRef.current = null; setIsReady(false); }; }, []); const loadModel = useCallback((url, modelOptions) => { engineRef.current?.engine?.loadModel(url, modelOptions); }, []); const goHome = useCallback(() => { engineRef.current?.engine?.CameraGoHome(); }, []); const activateMeasure = useCallback((mode) => { engineRef.current?.engine?.activateMeasure(mode); }, []); const deactivateMeasure = useCallback(() => { engineRef.current?.engine?.deactivateMeasure(); }, []); const setTheme = useCallback((theme) => { engineRef.current?.setTheme(theme); }, []); const setLocale = useCallback((locale) => { engineRef.current?.setLocale(locale); }, []); return { containerRef, engine: engineRef.current, isReady, error, loadModel, goHome, activateMeasure, deactivateMeasure, setTheme, setLocale }; } ``` ### 3. 组件封装 ```jsx // components/BimViewer.jsx import React, { useEffect, useImperativeHandle, forwardRef } from 'react'; import { useBimEngine } from '../hooks/useBimEngine'; export const BimViewer = 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 }); 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'; ``` ### 4. 使用组件 ```jsx // App.jsx import React, { useRef } from 'react'; import { BimViewer } from './components/BimViewer'; function App() { const viewerRef = useRef(null); const handleReady = (engine) => console.log('引擎已就绪', engine); const handleError = (error) => console.error('引擎错误', error); return (
); } export default App; ``` --- ## API 参考 ### BimEngine 主引擎类。 #### 构造函数 ```javascript import { BimEngine } from '@fishdingding/bim-engine-sdk'; new BimEngine(container, options) ``` | 参数 | 类型 | 说明 | |------|------|------| | container | HTMLElement \| string | 容器元素或容器 ID | | options.locale | string | 语言：'zh-CN' \| 'en-US'，默认 'zh-CN' | | options.theme | string | 主题：'light' \| 'dark'，默认 'light' | #### 属性 | 属性 | 类型 | 说明 | |------|------|------| | engine | EngineManager | 3D 引擎管理器 | | toolbar | ToolbarManager | 工具栏管理器 | | dialog | DialogManager | 弹窗管理器 | | measure | MeasureDialogManager | 测量面板管理器 | #### 方法 | 方法 | 参数 | 说明 | |------|------|------| | setLocale(locale) | 'zh-CN' \| 'en-US' | 设置语言 | | getLocale() | - | 获取当前语言 | | setTheme(theme) | 'light' \| 'dark' | 设置主题 | | destroy() | - | 销毁引擎 | --- ### EngineManager 3D 引擎管理器，通过 `engine.engine` 访问。 #### 方法 | 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | initialize(options) | EngineOptions | boolean | 初始化 3D 引擎 | | isInitialized() | - | boolean | 检查是否已初始化 | | loadModel(url, options) | string, ModelLoadOptions | void | 加载模型 | | CameraGoHome() | - | void | 回到主视角 | | activateMeasure(mode) | MeasureMode | void | 激活测量功能 | | deactivateMeasure() | - | void | 停用测量功能 | | getCurrentMeasureType() | - | MeasureMode \| null | 获取当前测量类型 | | getEngine() | - | any | 获取原始引擎实例 | | destroy() | - | void | 销毁引擎 | --- ## 类型定义 ### EngineOptions ```typescript interface EngineOptions { version?: 'v1' | 'v2'; // WebGL 版本，默认 'v2' showStats?: boolean; // 是否显示性能统计，默认 false showViewCube?: boolean; // 是否显示视图立方体，默认 true } ``` ### ModelLoadOptions ```typescript interface ModelLoadOptions { position?: [number, number, number]; // 位置，默认 [0, 0, 0] rotation?: [number, number, number]; // 旋转（弧度），默认 [0, 0, 0] scale?: [number, number, number]; // 缩放，默认 [1, 1, 1] id?: string; // 模型 ID（可选） } ``` ### MeasureMode ```typescript type MeasureMode = | 'distance' // 距离测量 | 'minDistance' // 最小距离测量 | 'angle' // 角度测量 | 'elevation' // 标高测量 | 'volume' // 体积测量 | 'laserDistance' // 激光测距 | 'slope' // 坡度测量 | 'spaceVolume'; // 空间体积测量 ``` --- ## 注意事项 1. **容器尺寸**：确保容器元素有明确的宽度和高度 2. **销毁清理**：页面关闭或组件卸载前务必调用 `destroy()` 3. **浏览器兼容**：需要支持 WebGL 的现代浏览器 --- ## 常见问题 ### Q: 模型加载失败？ 检查： - 模型路径是否正确 - 网络请求是否正常（F12 查看 Network） - 模型格式是否支持 ### Q: 如何监听引擎事件？ ```javascript engine.on('modelLoaded', (data) => { console.log('模型已加载', data); }); ``` --- ## 技术支持 - NPM 包地址：https://www.npmjs.com/package/@fishdingding/bim-engine-sdk - 如有问题，请联系技术支持