bim_xg/bim_engine
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 更新 SDK 构建产物和文档

Browse Source 
- 更新 SDK 构建文件 (es/umd)
- 更新 SDK 使用文档
- 删除 gujianzhu.glb 模型文件
- 更新 package.json 配置
- 调整 tab 组件样式和 vite 配置

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
yuding
2026-01-15 16:46:53 +08:00
parent a00d83e775
commit a930bc8a50
10 changed files with 85529 additions and 420 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
.DS_Store vendored
View File

Binary file not shown.

42630
demo/lib/bim-engine-sdk.es.js
View File

File diff suppressed because one or more lines are too long

BIN
demo/model/gujianzhu.glb
View File

Binary file not shown.

42632
dist/bim-engine-sdk.es.js vendored
View File

File diff suppressed because one or more lines are too long

2
dist/bim-engine-sdk.es.js.map vendored
View File

File diff suppressed because one or more lines are too long

2
dist/bim-engine-sdk.umd.js vendored
View File

File diff suppressed because one or more lines are too long

578
docs/SDK_USAGE.md
View File

@@ -16,13 +16,27 @@ BIM Engine SDK 是一个用于 3D BIM 模型展示的 JavaScript SDK，支持原
## 安装 ## 安装
### NPM 安装 ### NPM 安装（推荐）
```bash ```bash
npm install bim-engine-sdk npm install @fishdingding/bim-engine-sdk
``` ```
### CDN / 本地引入 ### Yarn 安装
```bash
yarn add @fishdingding/bim-engine-sdk
```
### PNPM 安装
```bash
pnpm add @fishdingding/bim-engine-sdk
```
### CDN / 本地文件引入
如果不使用包管理器，可以直接下载 JS 文件引入：
```html ```html
<script src="./lib/bim-engine-sdk.umd.js"></script> <script src="./lib/bim-engine-sdk.umd.js"></script>
@@ -32,17 +46,62 @@ npm install bim-engine-sdk
## 原生 HTML 使用 ## 原生 HTML 使用
### 基础示例 ### 方式一：使用 NPM + 构建工具
```html ```html
<!DOCTYPE html> <!DOCTYPE html>
<html lang="zh-CN"> <html lang="zh-CN">
<head> <head>
<meta charset="UTF-8"> <meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>BIM Engine Demo</title> <title>BIM Engine Demo</title>
<!-- 引入 SDK --> <style>
<script src="./lib/bim-engine-sdk.umd.js"></script> * { margin: 0; padding: 0; box-sizing: border-box; }
html, body { width: 100%; height: 100%; overflow: hidden; }
#app { width: 100%; height: 100%; }
</style>
</head>
<body>
<div id="app"></div>
<script type="module">
import { BimEngine } from '@fishdingding/bim-engine-sdk';
// 1. 创建引擎实例
const engine = new BimEngine('app', {
locale: 'zh-CN',
theme: 'light'
});
// 2. 初始化 3D 引擎
const success = engine.engine.initialize({
version: 'v2',
showStats: false,
showViewCube: true
});
if (success) {
// 3. 加载模型
engine.engine.loadModel('./model/your-model', {
position: [0, 0, 0],
rotation: [0, 0, 0],
scale: [1, 1, 1]
});
}
</script>
</body>
</html>
```
### 方式二：使用 UMD（无构建工具）
```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>BIM Engine Demo</title>
<!-- 引入 UMD 版本 -->
<script src="https://unpkg.com/@fishdingding/bim-engine-sdk/dist/bim-engine-sdk.umd.js"></script>
<style> <style>
* { margin: 0; padding: 0; box-sizing: border-box; } * { margin: 0; padding: 0; box-sizing: border-box; }
html, body { width: 100%; height: 100%; overflow: hidden; } html, body { width: 100%; height: 100%; overflow: hidden; }
@@ -55,32 +114,25 @@ npm install bim-engine-sdk
<script> <script>
// 1. 创建引擎实例 // 1. 创建引擎实例
const engine = new LyzBimEngineSDK.BimEngine('app', { const engine = new LyzBimEngineSDK.BimEngine('app', {
locale: 'zh-CN', // 语言：'zh-CN' | 'en-US' locale: 'zh-CN',
theme: 'light' // 主题：'light' | 'dark' theme: 'light'
}); });
// 2. 初始化 3D 引擎 // 2. 初始化 3D 引擎
const success = engine.engine.initialize({ const success = engine.engine.initialize({
version: 'v2', // WebGL 版本：'v1' | 'v2' version: 'v2',
showStats: false, // 是否显示性能统计 showStats: false,
showViewCube: true // 是否显示视图立方体 showViewCube: true
}); });
if (success) { if (success) {
console.log('3D 引擎初始化成功');
// 3. 加载模型 // 3. 加载模型
engine.engine.loadModel('./model/your-model', { engine.engine.loadModel('./model/your-model', {
position: [0, 0, 0], // 位置 [x, y, z] position: [0, 0, 0],
rotation: [0, 0, 0], // 旋转 [x, y, z]（弧度） rotation: [0, 0, 0],
scale: [1, 1, 1] // 缩放 [x, y, z] scale: [1, 1, 1]
}); });
} }
// 4. 页面卸载时销毁
window.addEventListener('beforeunload', () => {
engine.destroy();
});
</script> </script>
</body> </body>
</html> </html>
@@ -88,8 +140,7 @@ npm install bim-engine-sdk
### 完整功能示例 ### 完整功能示例
```html ```javascript
<script>
let engine = null; let engine = null;
// 初始化 // 初始化
@@ -105,7 +156,6 @@ npm install bim-engine-sdk
showViewCube: true showViewCube: true
}); });
// 加载模型
engine.engine.loadModel('./model/building'); engine.engine.loadModel('./model/building');
} }
@@ -115,8 +165,8 @@ npm install bim-engine-sdk
} }
// 激活测量功能 // 激活测量功能
function activateMeasure(mode) {
// mode: 'distance' | 'minDistance' | 'angle' | 'elevation' | 'volume' | 'laserDistance' | 'slope' | 'spaceVolume' // mode: 'distance' | 'minDistance' | 'angle' | 'elevation' | 'volume' | 'laserDistance' | 'slope' | 'spaceVolume'
function activateMeasure(mode) {
engine.engine.activateMeasure(mode); engine.engine.activateMeasure(mode);
} }
@@ -126,13 +176,13 @@ npm install bim-engine-sdk
} }
// 切换主题 // 切换主题
function toggleTheme() { function setTheme(theme) {
engine.setTheme('dark'); // 或 'light' engine.setTheme(theme); // 'light' | 'dark'
} }
// 切换语言 // 切换语言
function toggleLocale() { function setLocale(locale) {
engine.setLocale('en-US'); // 或 'zh-CN' engine.setLocale(locale); // 'zh-CN' | 'en-US'
} }
// 销毁 // 销毁
@@ -141,68 +191,56 @@ npm install bim-engine-sdk
} }
window.onload = init; window.onload = init;
</script>
``` ```
--- ---
## Vue 3 使用 ## Vue 3 使用
### 安装依赖 ### 1. 安装
```bash ```bash
npm install bim-engine-sdk npm install @fishdingding/bim-engine-sdk
``` ```
### 组件封装 ### 2. 组件封装
```vue ```vue
<!-- BimViewer.vue --> <!-- components/BimViewer.vue -->
<template> <template>
<div ref="containerRef" class="bim-viewer"></div> <div ref="containerRef" class="bim-viewer"></div>
</template> </template>
<script setup lang="ts"> <script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'; import { ref, onMounted, onBeforeUnmount } from 'vue';
import { BimEngine } from 'bim-engine-sdk'; import { BimEngine } from '@fishdingding/bim-engine-sdk';
import type { EngineOptions, ModelLoadOptions } from 'bim-engine-sdk';
// Props // Props
interface Props { const props = defineProps({
modelUrl?: string; modelUrl: { type: String, default: '' },
modelOptions?: ModelLoadOptions; modelOptions: { type: Object, default: () => ({}) },
engineOptions?: Omit<EngineOptions, 'container'>; engineOptions: { type: Object, default: () => ({}) },
locale?: 'zh-CN' | 'en-US'; locale: { type: String, default: 'zh-CN' },
theme?: 'light' | 'dark'; theme: { type: String, default: 'light' }
}
const props = withDefaults(defineProps<Props>(), {
locale: 'zh-CN',
theme: 'light'
}); });
// Emits // Emits
const emit = defineEmits<{ const emit = defineEmits(['ready', 'error']);
(e: 'ready', engine: BimEngine): void;
(e: 'error', error: Error): void;
}>();
// Refs // Refs
const containerRef = ref<HTMLElement | null>(null); const containerRef = ref(null);
let engine: BimEngine | null = null; let engine = null;
// 初始化引擎 // 初始化引擎
const initEngine = () => { const initEngine = () => {
if (!containerRef.value) return; if (!containerRef.value) return;
try { try {
// 创建引擎实例
engine = new BimEngine(containerRef.value, { engine = new BimEngine(containerRef.value, {
locale: props.locale, locale: props.locale,
theme: props.theme theme: props.theme
}); });
// 初始化 3D 引擎
const success = engine.engine?.initialize({ const success = engine.engine?.initialize({
version: 'v2', version: 'v2',
showStats: false, showStats: false,
@@ -212,8 +250,6 @@ const initEngine = () => {
if (success) { if (success) {
emit('ready', engine); emit('ready', engine);
// 加载模型
if (props.modelUrl) { if (props.modelUrl) {
engine.engine?.loadModel(props.modelUrl, props.modelOptions); engine.engine?.loadModel(props.modelUrl, props.modelOptions);
} }
@@ -221,51 +257,22 @@ const initEngine = () => {
throw new Error('3D 引擎初始化失败'); throw new Error('3D 引擎初始化失败');
} }
} catch (error) { } catch (error) {
emit('error', error as Error); emit('error', error);
} }
}; };
// 暴露方法给父组件 // 暴露方法
defineExpose({ defineExpose({
// 获取引擎实例
getEngine: () => engine, getEngine: () => engine,
loadModel: (url, options) => engine?.engine?.loadModel(url, options),
// 加载模型 goHome: () => engine?.engine?.CameraGoHome(),
loadModel: (url: string, options?: ModelLoadOptions) => { activateMeasure: (mode) => engine?.engine?.activateMeasure(mode),
engine?.engine?.loadModel(url, options); deactivateMeasure: () => engine?.engine?.deactivateMeasure(),
}, setTheme: (theme) => engine?.setTheme(theme),
setLocale: (locale) => engine?.setLocale(locale)
// 回到主视角
goHome: () => {
engine?.engine?.CameraGoHome();
},
// 激活测量
activateMeasure: (mode: string) => {
engine?.engine?.activateMeasure(mode as any);
},
// 停用测量
deactivateMeasure: () => {
engine?.engine?.deactivateMeasure();
},
// 切换主题
setTheme: (theme: 'light' | 'dark') => {
engine?.setTheme(theme);
},
// 切换语言
setLocale: (locale: 'zh-CN' | 'en-US') => {
engine?.setLocale(locale);
}
});
// 生命周期
onMounted(() => {
initEngine();
}); });
onMounted(() => initEngine());
onBeforeUnmount(() => { onBeforeUnmount(() => {
engine?.destroy(); engine?.destroy();
engine = null; engine = null;
@@ -280,7 +287,7 @@ onBeforeUnmount(() => {
</style> </style>
``` ```
### 使用组件 ### 3. 使用组件
```vue ```vue
<!-- App.vue --> <!-- App.vue -->
@@ -304,32 +311,23 @@ onBeforeUnmount(() => {
</div> </div>
</template> </template>
<script setup lang="ts"> <script setup>
import { ref } from 'vue'; import { ref } from 'vue';
import BimViewer from './components/BimViewer.vue'; import BimViewer from './components/BimViewer.vue';
import type { BimEngine } from 'bim-engine-sdk';
const viewerRef = ref<InstanceType<typeof BimViewer> | null>(null); const viewerRef = ref(null);
const onEngineReady = (engine: BimEngine) => { const onEngineReady = (engine) => {
console.log('引擎已就绪', engine); console.log('引擎已就绪', engine);
}; };
const onEngineError = (error: Error) => { const onEngineError = (error) => {
console.error('引擎错误', error); console.error('引擎错误', error);
}; };
const goHome = () => { const goHome = () => viewerRef.value?.goHome();
viewerRef.value?.goHome(); const measure = (mode) => viewerRef.value?.activateMeasure(mode);
}; const stopMeasure = () => viewerRef.value?.deactivateMeasure();
const measure = (mode: string) => {
viewerRef.value?.activateMeasure(mode);
};
const stopMeasure = () => {
viewerRef.value?.deactivateMeasure();
};
</script> </script>
<style> <style>
@@ -338,7 +336,6 @@ const stopMeasure = () => {
height: 100vh; height: 100vh;
position: relative; position: relative;
} }
.toolbar { .toolbar {
position: absolute; position: absolute;
top: 20px; top: 20px;
@@ -352,47 +349,32 @@ const stopMeasure = () => {
## Vue 2 使用 ## Vue 2 使用
### 安装依赖 ### 1. 安装
```bash ```bash
npm install bim-engine-sdk npm install @fishdingding/bim-engine-sdk
``` ```
### 组件封装 ### 2. 组件封装
```vue ```vue
<!-- BimViewer.vue --> <!-- components/BimViewer.vue -->
<template> <template>
<div ref="container" class="bim-viewer"></div> <div ref="container" class="bim-viewer"></div>
</template> </template>
<script> <script>
import { BimEngine } from 'bim-engine-sdk'; import { BimEngine } from '@fishdingding/bim-engine-sdk';
export default { export default {
name: 'BimViewer', name: 'BimViewer',
props: { props: {
modelUrl: { modelUrl: { type: String, default: '' },
type: String, modelOptions: { type: Object, default: () => ({}) },
default: '' engineOptions: { type: Object, default: () => ({}) },
}, locale: { type: String, default: 'zh-CN' },
modelOptions: { theme: { type: String, default: 'light' }
type: Object,
default: () => ({})
},
engineOptions: {
type: Object,
default: () => ({})
},
locale: {
type: String,
default: 'zh-CN'
},
theme: {
type: String,
default: 'light'
}
}, },
data() { data() {
@@ -412,13 +394,11 @@ export default {
methods: { methods: {
initEngine() { initEngine() {
try { try {
// 创建引擎实例
this.engine = new BimEngine(this.$refs.container, { this.engine = new BimEngine(this.$refs.container, {
locale: this.locale, locale: this.locale,
theme: this.theme theme: this.theme
}); });
// 初始化 3D 引擎
const success = this.engine.engine.initialize({ const success = this.engine.engine.initialize({
version: 'v2', version: 'v2',
showStats: false, showStats: false,
@@ -428,8 +408,6 @@ export default {
if (success) { if (success) {
this.$emit('ready', this.engine); this.$emit('ready', this.engine);
// 加载模型
if (this.modelUrl) { if (this.modelUrl) {
this.engine.engine.loadModel(this.modelUrl, this.modelOptions); this.engine.engine.loadModel(this.modelUrl, this.modelOptions);
} }
@@ -449,33 +427,13 @@ export default {
}, },
// 公开方法 // 公开方法
getEngine() { getEngine() { return this.engine; },
return this.engine; loadModel(url, options) { this.engine?.engine?.loadModel(url, options); },
}, goHome() { this.engine?.engine?.CameraGoHome(); },
activateMeasure(mode) { this.engine?.engine?.activateMeasure(mode); },
loadModel(url, options) { deactivateMeasure() { this.engine?.engine?.deactivateMeasure(); },
this.engine?.engine?.loadModel(url, options); setTheme(theme) { this.engine?.setTheme(theme); },
}, setLocale(locale) { this.engine?.setLocale(locale); }
goHome() {
this.engine?.engine?.CameraGoHome();
},
activateMeasure(mode) {
this.engine?.engine?.activateMeasure(mode);
},
deactivateMeasure() {
this.engine?.engine?.deactivateMeasure();
},
setTheme(theme) {
this.engine?.setTheme(theme);
},
setLocale(locale) {
this.engine?.setLocale(locale);
}
} }
}; };
</script> </script>
@@ -488,7 +446,7 @@ export default {
</style> </style>
``` ```
### 使用组件 ### 3. 使用组件
```vue ```vue
<!-- App.vue --> <!-- App.vue -->
@@ -517,48 +475,21 @@ import BimViewer from './components/BimViewer.vue';
export default { export default {
name: 'App', name: 'App',
components: { BimViewer },
components: {
BimViewer
},
methods: { methods: {
onEngineReady(engine) { onEngineReady(engine) { console.log('引擎已就绪', engine); },
console.log('引擎已就绪', engine); onEngineError(error) { console.error('引擎错误', error); },
}, goHome() { this.$refs.viewer.goHome(); },
measure(mode) { this.$refs.viewer.activateMeasure(mode); },
onEngineError(error) { stopMeasure() { this.$refs.viewer.deactivateMeasure(); }
console.error('引擎错误', error);
},
goHome() {
this.$refs.viewer.goHome();
},
measure(mode) {
this.$refs.viewer.activateMeasure(mode);
},
stopMeasure() {
this.$refs.viewer.deactivateMeasure();
}
} }
}; };
</script> </script>
<style> <style>
.app { .app { width: 100vw; height: 100vh; position: relative; }
width: 100vw; .toolbar { position: absolute; top: 20px; left: 20px; z-index: 100; }
height: 100vh;
position: relative;
}
.toolbar {
position: absolute;
top: 20px;
left: 20px;
z-index: 100;
}
</style> </style>
``` ```
@@ -566,48 +497,34 @@ export default {
## React 使用 ## React 使用
### 安装依赖 ### 1. 安装
```bash ```bash
npm install bim-engine-sdk npm install @fishdingding/bim-engine-sdk
``` ```
### Hook 封装 ### 2. Hook 封装
```tsx ```jsx
// hooks/useBimEngine.ts // hooks/useBimEngine.js
import { useEffect, useRef, useState, useCallback } from 'react'; import { useEffect, useRef, useState, useCallback } from 'react';
import { BimEngine } from 'bim-engine-sdk'; import { BimEngine } from '@fishdingding/bim-engine-sdk';
import type { EngineOptions, ModelLoadOptions } from 'bim-engine-sdk';
type MeasureMode = 'distance' | 'minDistance' | 'angle' | 'elevation' | 'volume' | 'laserDistance' | 'slope' | 'spaceVolume'; export function useBimEngine(options = {}) {
const containerRef = useRef(null);
interface UseBimEngineOptions { const engineRef = useRef(null);
locale?: 'zh-CN' | 'en-US';
theme?: 'light' | 'dark';
engineOptions?: Omit<EngineOptions, 'container'>;
onReady?: (engine: BimEngine) => void;
onError?: (error: Error) => void;
}
export function useBimEngine(options: UseBimEngineOptions = {}) {
const containerRef = useRef<HTMLDivElement>(null);
const engineRef = useRef<BimEngine | null>(null);
const [isReady, setIsReady] = useState(false); const [isReady, setIsReady] = useState(false);
const [error, setError] = useState<Error | null>(null); const [error, setError] = useState(null);
// 初始化引擎
useEffect(() => { useEffect(() => {
if (!containerRef.current) return; if (!containerRef.current) return;
try { try {
// 创建引擎实例
const engine = new BimEngine(containerRef.current, { const engine = new BimEngine(containerRef.current, {
locale: options.locale || 'zh-CN', locale: options.locale || 'zh-CN',
theme: options.theme || 'light' theme: options.theme || 'light'
}); });
// 初始化 3D 引擎
const success = engine.engine?.initialize({ const success = engine.engine?.initialize({
version: 'v2', version: 'v2',
showStats: false, showStats: false,
@@ -623,12 +540,10 @@ export function useBimEngine(options: UseBimEngineOptions = {}) {
throw new Error('3D 引擎初始化失败'); throw new Error('3D 引擎初始化失败');
} }
} catch (err) { } catch (err) {
const error = err as Error; setError(err);
setError(error); options.onError?.(err);
options.onError?.(error);
} }
// 清理
return () => { return () => {
engineRef.current?.destroy(); engineRef.current?.destroy();
engineRef.current = null; engineRef.current = null;
@@ -636,33 +551,27 @@ export function useBimEngine(options: UseBimEngineOptions = {}) {
}; };
}, []); }, []);
// 加载模型 const loadModel = useCallback((url, modelOptions) => {
const loadModel = useCallback((url: string, modelOptions?: ModelLoadOptions) => {
engineRef.current?.engine?.loadModel(url, modelOptions); engineRef.current?.engine?.loadModel(url, modelOptions);
}, []); }, []);
// 回到主视角
const goHome = useCallback(() => { const goHome = useCallback(() => {
engineRef.current?.engine?.CameraGoHome(); engineRef.current?.engine?.CameraGoHome();
}, []); }, []);
// 激活测量 const activateMeasure = useCallback((mode) => {
const activateMeasure = useCallback((mode: MeasureMode) => {
engineRef.current?.engine?.activateMeasure(mode); engineRef.current?.engine?.activateMeasure(mode);
}, []); }, []);
// 停用测量
const deactivateMeasure = useCallback(() => { const deactivateMeasure = useCallback(() => {
engineRef.current?.engine?.deactivateMeasure(); engineRef.current?.engine?.deactivateMeasure();
}, []); }, []);
// 切换主题 const setTheme = useCallback((theme) => {
const setTheme = useCallback((theme: 'light' | 'dark') => {
engineRef.current?.setTheme(theme); engineRef.current?.setTheme(theme);
}, []); }, []);
// 切换语言 const setLocale = useCallback((locale) => {
const setLocale = useCallback((locale: 'zh-CN' | 'en-US') => {
engineRef.current?.setLocale(locale); engineRef.current?.setLocale(locale);
}, []); }, []);
@@ -681,26 +590,14 @@ export function useBimEngine(options: UseBimEngineOptions = {}) {
} }
``` ```
### 组件封装 ### 3. 组件封装
```tsx ```jsx
// components/BimViewer.tsx // components/BimViewer.jsx
import React, { useEffect } from 'react'; import React, { useEffect, useImperativeHandle, forwardRef } from 'react';
import { useBimEngine } from '../hooks/useBimEngine'; import { useBimEngine } from '../hooks/useBimEngine';
import type { ModelLoadOptions } from 'bim-engine-sdk';
interface BimViewerProps { export const BimViewer = forwardRef((props, ref) => {
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<any, BimViewerProps>((props, ref) => {
const { const {
modelUrl, modelUrl,
modelOptions, modelOptions,
@@ -722,15 +619,9 @@ export const BimViewer = React.forwardRef<any, BimViewerProps>((props, ref) => {
deactivateMeasure, deactivateMeasure,
setTheme, setTheme,
setLocale setLocale
} = useBimEngine({ } = useBimEngine({ locale, theme, onReady, onError });
locale,
theme,
onReady,
onError
});
// 暴露方法给父组件 useImperativeHandle(ref, () => ({
React.useImperativeHandle(ref, () => ({
getEngine: () => engine, getEngine: () => engine,
loadModel, loadModel,
goHome, goHome,
@@ -740,7 +631,6 @@ export const BimViewer = React.forwardRef<any, BimViewerProps>((props, ref) => {
setLocale setLocale
})); }));
// 加载模型
useEffect(() => { useEffect(() => {
if (isReady && modelUrl) { if (isReady && modelUrl) {
loadModel(modelUrl, modelOptions); loadModel(modelUrl, modelOptions);
@@ -751,11 +641,7 @@ export const BimViewer = React.forwardRef<any, BimViewerProps>((props, ref) => {
<div <div
ref={containerRef} ref={containerRef}
className={className} className={className}
style={{ style={{ width: '100%', height: '100%', ...style }}
width: '100%',
height: '100%',
...style
}}
/> />
); );
}); });
@@ -763,35 +649,18 @@ export const BimViewer = React.forwardRef<any, BimViewerProps>((props, ref) => {
BimViewer.displayName = 'BimViewer'; BimViewer.displayName = 'BimViewer';
``` ```
### 使用组件 ### 4. 使用组件
```tsx ```jsx
// App.tsx // App.jsx
import React, { useRef } from 'react'; import React, { useRef } from 'react';
import { BimViewer } from './components/BimViewer'; import { BimViewer } from './components/BimViewer';
function App() { function App() {
const viewerRef = useRef<any>(null); const viewerRef = useRef(null);
const handleReady = (engine: any) => { const handleReady = (engine) => console.log('引擎已就绪', engine);
console.log('引擎已就绪', engine); const handleError = (error) => console.error('引擎错误', error);
};
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 ( return (
<div style={{ width: '100vw', height: '100vh', position: 'relative' }}> <div style={{ width: '100vw', height: '100vh', position: 'relative' }}>
@@ -806,9 +675,9 @@ function App() {
/> />
<div style={{ position: 'absolute', top: 20, left: 20, zIndex: 100 }}> <div style={{ position: 'absolute', top: 20, left: 20, zIndex: 100 }}>
<button onClick={goHome}>主视角</button> <button onClick={() => viewerRef.current?.goHome()}>主视角</button>
<button onClick={() => measure('distance')}>距离测量</button> <button onClick={() => viewerRef.current?.activateMeasure('distance')}>距离测量</button>
<button onClick={stopMeasure}>停止测量</button> <button onClick={() => viewerRef.current?.deactivateMeasure()}>停止测量</button>
</div> </div>
</div> </div>
); );
@@ -823,22 +692,21 @@ export default App;
### BimEngine ### BimEngine
主引擎类，用于创建和管理 BIM 引擎实例。 主引擎类。
#### 构造函数 #### 构造函数
```typescript ```javascript
new BimEngine(container: HTMLElement | string, options?: { import { BimEngine } from '@fishdingding/bim-engine-sdk';
locale?: 'zh-CN' | 'en-US';
theme?: 'light' | 'dark'; new BimEngine(container, options)
})
``` ```
| 参数 | 类型 | 说明 | | 参数 | 类型 | 说明 |
|------|------|------| |------|------|------|
| container | HTMLElement \| string | 容器元素或容器 ID | | container | HTMLElement \| string | 容器元素或容器 ID |
| options.locale | string | 语言设置，默认 'zh-CN' | | options.locale | string | 语言：'zh-CN' \| 'en-US'，默认 'zh-CN' |
| options.theme | string | 主题设置，默认 'light' | | options.theme | string | 主题：'light' \| 'dark'，默认 'light' |
#### 属性 #### 属性
@@ -851,13 +719,12 @@ new BimEngine(container: HTMLElement | string, options?: {
#### 方法 #### 方法
| 方法 | 参数 | 返回值 | 说明 | | 方法 | 参数 | 说明 |
|------|------|--------|------| |------|------|------|
| setLocale | locale: 'zh-CN' \| 'en-US' | void | 设置语言 | | setLocale(locale) | 'zh-CN' \| 'en-US' | 设置语言 |
| getLocale | - | string | 获取当前语言 | | getLocale() | - | 获取当前语言 |
| setTheme | theme: 'light' \| 'dark' | void | 设置主题 | | setTheme(theme) | 'light' \| 'dark' | 设置主题 |
| setCustomTheme | theme: ThemeConfig | void | 设置自定义主题 | | destroy() | - | 销毁引擎 |
| destroy | - | void | 销毁引擎 |
--- ---
@@ -869,15 +736,15 @@ new BimEngine(container: HTMLElement | string, options?: {
| 方法 | 参数 | 返回值 | 说明 | | 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------| |------|------|--------|------|
| initialize | options?: EngineOptions | boolean | 初始化 3D 引擎 | | initialize(options) | EngineOptions | boolean | 初始化 3D 引擎 |
| isInitialized | - | boolean | 检查是否已初始化 | | isInitialized() | - | boolean | 检查是否已初始化 |
| loadModel | url: string, options?: ModelLoadOptions | void | 加载模型 | | loadModel(url, options) | string, ModelLoadOptions | void | 加载模型 |
| CameraGoHome | - | void | 回到主视角 | | CameraGoHome() | - | void | 回到主视角 |
| activateMeasure | mode: MeasureMode | void | 激活测量功能 | | activateMeasure(mode) | MeasureMode | void | 激活测量功能 |
| deactivateMeasure | - | void | 停用测量功能 | | deactivateMeasure() | - | void | 停用测量功能 |
| getCurrentMeasureType | - | MeasureMode \| null | 获取当前测量类型 | | getCurrentMeasureType() | - | MeasureMode \| null | 获取当前测量类型 |
| getEngine | - | any | 获取原始引擎实例 | | getEngine() | - | any | 获取原始引擎实例 |
| destroy | - | void | 销毁引擎 | | destroy() | - | void | 销毁引擎 |
--- ---
@@ -887,11 +754,9 @@ new BimEngine(container: HTMLElement | string, options?: {
```typescript ```typescript
interface EngineOptions { interface EngineOptions {
container: HTMLElement; // 容器元素 version?: 'v1' | 'v2'; // WebGL 版本，默认 'v2'
backgroundColor?: number | string; // 背景色 showStats?: boolean; // 是否显示性能统计，默认 false
version?: 'v1' | 'v2'; // WebGL 版本 showViewCube?: boolean; // 是否显示视图立方体，默认 true
showStats?: boolean; // 是否显示性能统计
showViewCube?: boolean; // 是否显示视图立方体
} }
``` ```
@@ -899,10 +764,10 @@ interface EngineOptions {
```typescript ```typescript
interface ModelLoadOptions { interface ModelLoadOptions {
position?: [number, number, number]; // 位置 [x, y, z] position?: [number, number, number]; // 位置，默认 [0, 0, 0]
rotation?: [number, number, number]; // 旋转 [x, y, z]（弧度） rotation?: [number, number, number]; // 旋转（弧度），默认 [0, 0, 0]
scale?: [number, number, number]; // 缩放 [x, y, z] scale?: [number, number, number]; // 缩放，默认 [1, 1, 1]
id?: string; // 模型 ID id?: string; // 模型 ID（可选）
} }
``` ```
@@ -924,53 +789,25 @@ type MeasureMode =
## 注意事项 ## 注意事项
1. **容器尺寸**：确保容器元素有明确的宽度和高度，否则 3D 引擎可能无法正常渲染。 1. **容器尺寸**：确保容器元素有明确的宽度和高度
2. **模型路径**：模型路径应为相对于 HTML 页面的路径，或者完整的 URL。 2. **销毁清理**：页面关闭或组件卸载前务必调用 `destroy()`
3. **销毁清理**：在组件卸载或页面关闭前，务必调用 `destroy()` 方法释放资源。 3. **浏览器兼容**：需要支持 WebGL 的现代浏览器
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: 模型加载失败怎么办？ ### Q: 模型加载失败？
A: 检查以下几点： 检查：
- 模型路径是否正确 - 模型路径是否正确
- 模型格式是否支持
- 网络请求是否正常（F12 查看 Network） - 网络请求是否正常（F12 查看 Network）
- Draco 解码器是否正确部署 - 模型格式是否支持
### Q: 如何自定义主题？
A: 使用 `setCustomTheme` 方法：
```javascript
engine.setCustomTheme({
background: '#1a1a2e',
textPrimary: '#ffffff',
textSecondary: '#cccccc',
// ... 更多配置
});
```
### Q: 如何监听引擎事件？ ### Q: 如何监听引擎事件？
A: 使用 `on` 方法监听事件：
```javascript ```javascript
engine.on('modelLoaded', (data) => { engine.on('modelLoaded', (data) => {
console.log('模型已加载', data); console.log('模型已加载', data);
@@ -981,4 +818,5 @@ engine.on('modelLoaded', (data) => {
## 技术支持 ## 技术支持
如有问题，请联系技术支持或提交 Issue。 - NPM 包地址：https://www.npmjs.com/package/@fishdingding/bim-engine-sdk
- 如有问题，请联系技术支持

29
package.json
View File

@@ -1,6 +1,6 @@
{ {
"name": "bim-engine-sdk", "name": "@fishdingding/bim-engine-sdk",
"version": "1.0.0", "version": "1.0.2",
"description": "BIM Engine SDK for Vue2, Vue3, React and HTML", "description": "BIM Engine SDK for Vue2, Vue3, React and HTML",
"main": "./dist/bim-engine-sdk.umd.js", "main": "./dist/bim-engine-sdk.umd.js",
"module": "./dist/bim-engine-sdk.es.js", "module": "./dist/bim-engine-sdk.es.js",
@@ -24,16 +24,33 @@
"copy:demo-vue": "mkdir -p demo-vue/public/lib && cp dist/bim-engine-sdk.es.js dist/bim-engine-sdk.umd.js dist/bim-engine-sdk.umd.js.map demo-vue/public/lib/", "copy:demo-vue": "mkdir -p demo-vue/public/lib && cp dist/bim-engine-sdk.es.js dist/bim-engine-sdk.umd.js dist/bim-engine-sdk.umd.js.map demo-vue/public/lib/",
"dev:demo": "npm run build && npm run copy:demo-all && cd demo && npm run dev", "dev:demo": "npm run build && npm run copy:demo-all && cd demo && npm run dev",
"dev:demo-vue": "npm run build && npm run copy:demo-vue && cd demo-vue && npm run dev", "dev:demo-vue": "npm run build && npm run copy:demo-vue && cd demo-vue && npm run dev",
"dev:all": "npm run dev:demo & npm run dev:demo-vue" "dev:all": "npm run dev:demo & npm run dev:demo-vue",
"prepublishOnly": "npm run build"
}, },
"keywords": [ "keywords": [
"bim", "bim",
"sdk", "sdk",
"vue", "vue",
"react" "vue2",
"vue3",
"react",
"3d",
"webgl",
"three",
"threejs",
"viewer",
"model"
], ],
"author": "", "author": "LYZ",
"license": "ISC", "license": "MIT",
"repository": {
"type": "git",
"url": "http://123.60.156.158:13000/bim_engine/bimEngine.git"
},
"homepage": "http://123.60.156.158:13000/bim_engine/bimEngine",
"bugs": {
"url": "http://123.60.156.158:13000/bim_engine/bimEngine/issues"
},
"devDependencies": { "devDependencies": {
"@types/node": "^25.0.2", "@types/node": "^25.0.2",
"typescript": "^5.9.3", "typescript": "^5.9.3",

3
src/components/tab/index.css
View File

@@ -10,11 +10,12 @@
.bim-tab__nav { .bim-tab__nav {
display: flex; display: flex;
align-items: center; align-items: center;
justify-content: center; justify-content: space-around;
background: transparent; background: transparent;
} }
.bim-tab__item { .bim-tab__item {
flex:1;
display: inline-flex; display: inline-flex;
align-items: center; align-items: center;
justify-content: center; justify-content: center;

3
vite.config.ts
View File

@@ -31,9 +31,10 @@ export default defineConfig(() => {
fileName: (format) => `bim-engine-sdk.${format}.js`, fileName: (format) => `bim-engine-sdk.${format}.js`,
}, },
rollupOptions: { rollupOptions: {
// 不再需要排除 Vue
output: { output: {
globals: {}, globals: {},
// 禁用代码分割，将所有代码打包到一个文件
inlineDynamicImports: true,
}, },
}, },
sourcemap: true, sourcemap: true,