@caojinyu111/vue-bim-viewer 0.3.1 → 0.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/API.md +193 -77
- package/README.md +68 -13
- package/dist/MineViewer.d.ts +4 -1
- package/dist/dist-BewvulRQ.js +1359 -0
- package/dist/dist-DSgZUDDY.cjs +2 -0
- package/dist/gis-imagery.d.ts +20 -2
- package/dist/gis.d.ts +2 -2
- package/dist/index.cjs +23 -2
- package/dist/index.d.ts +1 -1
- package/dist/index.js +2403 -1284
- package/dist/plugin-CYagUb1J.js +4779 -0
- package/dist/plugin-Cs6eHojx.cjs +1 -0
- package/dist/style.css +1 -1
- package/dist/types.d.ts +17 -5
- package/package.json +11 -15
package/API.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# API 与集成指南
|
|
2
2
|
|
|
3
|
-
适用版本：**0.3.
|
|
3
|
+
适用版本：**0.3.3**。本文面向在 Vue 3 应用中集成 `@caojinyu111/vue-bim-viewer` 的开发者，说明模型资源约定、组件接口、业务接入方式及使用限制。
|
|
4
4
|
|
|
5
5
|
SDK 使用 JavaScript 实现，同时提供独立的 TypeScript 类型声明。除 TypeScript 接入章节外，组件与业务示例均使用 JavaScript。快速安装见 [README](./README.md)；参数字段和可选性可结合发布包中的声明文件查阅。
|
|
6
6
|
|
|
@@ -16,7 +16,7 @@ SDK 使用 JavaScript 实现，同时提供独立的 TypeScript 类型声明。
|
|
|
16
16
|
6. [外观修改、差异与保存](#appearance)
|
|
17
17
|
7. [Marker 标签与弹窗](#markers)
|
|
18
18
|
8. [事件与插槽参考](#events-slots)
|
|
19
|
-
9. [GIS
|
|
19
|
+
9. [GIS 配准、影像与 DEM](#gis)
|
|
20
20
|
10. [公开类型索引](#types)
|
|
21
21
|
11. [模块入口与类型声明](#development)
|
|
22
22
|
12. [常见问题与限制](#troubleshooting)
|
|
@@ -27,27 +27,30 @@ SDK 使用 JavaScript 实现，同时提供独立的 TypeScript 类型声明。
|
|
|
27
27
|
|
|
28
28
|
### 1.1 功能清单
|
|
29
29
|
|
|
30
|
-
| 能力 | 当前支持内容 | 使用入口
|
|
31
|
-
| ---------- | --------------------------------------------------------------- |
|
|
32
|
-
| 模型加载 | 通过 Manifest 加载 GLB/glTF，处理外部 buffer/image 和可选元数据 | `MineViewer`、`modelSource`
|
|
33
|
-
| 三维浏览 | 拖动旋转、滚轮缩放、右键平移、容器尺寸适配、初始全模型视角 | `initialView`、`resetView()`
|
|
34
|
-
|
|
|
35
|
-
|
|
|
36
|
-
|
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
|
41
|
-
|
|
|
42
|
-
|
|
|
43
|
-
|
|
|
44
|
-
|
|
|
30
|
+
| 能力 | 当前支持内容 | 使用入口 |
|
|
31
|
+
| ---------- | --------------------------------------------------------------- | ------------------------------------------------ |
|
|
32
|
+
| 模型加载 | 通过 Manifest 加载 GLB/glTF，处理外部 buffer/image 和可选元数据 | `MineViewer`、`modelSource` |
|
|
33
|
+
| 三维浏览 | 拖动旋转、滚轮缩放、右键平移、容器尺寸适配、初始全模型视角 | `initialView`、`resetView()` |
|
|
34
|
+
| 视角导航 | Home、26 方向骰子、六个标准方向方法及实时显隐 | `navigation`、`setViewDirection()` |
|
|
35
|
+
| 构件树 | 内置目录、名称搜索、分支显隐、选中定位及完整树查询 | `navigation.componentTree`、`getComponentTree()` |
|
|
36
|
+
| 场景查询 | 源场景结构快照、活的 Three.js 根节点、对象对应 ID | `getSceneTree()` 等 |
|
|
37
|
+
| 构件交互 | 三维拾取、按 ID 选择、青绿色高亮与细轮廓、相机定位、清除选择 | `selectComponent()`、`focusComponent()` |
|
|
38
|
+
| 锚点查询 | 对象原点、包围盒中心、包围盒 Y 轴顶部 | `getComponentAnchor()` |
|
|
39
|
+
| 外观控制 | 显隐、透明度、颜色、批量设置及父子继承 | `setComponentAppearance()` 等 |
|
|
40
|
+
| 差异与恢复 | 当前净差异、合并导入、恢复单节点或全部覆盖 | `getAppearanceChanges()` 等 |
|
|
41
|
+
| 标签 | 原始模型坐标点、构件锚点、模型偏移、屏幕偏移 | `markers` |
|
|
42
|
+
| 弹窗与模板 | 默认标签/弹窗、自定义插槽、点击切换和关闭 | `marker`、`marker-popup` |
|
|
43
|
+
| GIS 配准 | 三点或多点水平配准、可选高程、ENU/ECEF 矩阵、误差报告 | `createGisPlacement()` |
|
|
44
|
+
| 地图影像 | 有限范围天地图影像、透明度、独立加载状态 | `gis`、`gis-status` |
|
|
45
|
+
| DEM 地形 | 相对预览、真实高程转换、缺测回退及独立准备状态 | `gis.terrain`、`terrain-status` |
|
|
46
|
+
| 场景背景 | 纯色或普通静态图片，居中 cover，可响应式更新 | `background`、`background-error` |
|
|
47
|
+
| 树展开工具 | 按源顺序深度优先展开构件树 | `flattenComponentTree()` |
|
|
45
48
|
|
|
46
49
|
### 1.2 SDK 与宿主的分工
|
|
47
50
|
|
|
48
51
|
SDK 管理模型加载、渲染、构件索引、外观运行状态、选择、标签投影和资源清理。宿主通过参数、事件及公开方法接入业务。
|
|
49
52
|
|
|
50
|
-
以下由宿主负责：模型 URL
|
|
53
|
+
以下由宿主负责：模型 URL 与访问权限、业务按钮、标签内容、localStorage/服务端保存、JSON 文件选择与下载、地图服务密钥、控制点及真实高程基准转换。SDK 内置构件目录与名称搜索，通过 `gis` 属性接入可选影像与 DEM。宿主可通过公开查询与外观方法自建扩展面板；SDK 不依赖业务 UI 组件库。
|
|
51
54
|
|
|
52
55
|
当前包的运行时命名导出只有：
|
|
53
56
|
|
|
@@ -64,18 +67,18 @@ import '@caojinyu111/vue-bim-viewer/style.css'
|
|
|
64
67
|
|
|
65
68
|
### 2.1 安装依赖
|
|
66
69
|
|
|
67
|
-
在 Vue 应用中安装 SDK
|
|
70
|
+
在 Vue 应用中安装 SDK：
|
|
68
71
|
|
|
69
72
|
```sh
|
|
70
|
-
npm install @caojinyu111/vue-bim-viewer@0.3.
|
|
73
|
+
npm install @caojinyu111/vue-bim-viewer@0.3.3
|
|
71
74
|
```
|
|
72
75
|
|
|
73
|
-
运行环境要求 Vue 3.5
|
|
76
|
+
运行环境要求 Vue **3.5.43**、Three.js **0.183.1** 和支持 WebGL2 的浏览器。Vue 与 Three.js 为精确版本的共享 peerDependencies，npm 7+ 会补齐尚未安装的 peer；已有不兼容版本的宿主先执行 `npm install vue@3.5.43 three@0.183.1`。three-tile **0.12.2** 与 Proj4js 随 SDK 安装，three-tile 随 SDK 构建。启用 GIS 地图还需要 `fetch`、`createImageBitmap`、`AbortSignal.any`、`AbortSignal.timeout` 和 `OffscreenCanvas`；启用 DEM 额外需要 `DecompressionStream`。SSR 只能在客户端挂载组件。
|
|
74
77
|
|
|
75
78
|
TypeScript 应用额外安装 Three.js 类型声明：
|
|
76
79
|
|
|
77
80
|
```sh
|
|
78
|
-
npm install --save-dev @types/three@0.
|
|
81
|
+
npm install --save-dev @types/three@0.183.1
|
|
79
82
|
```
|
|
80
83
|
|
|
81
84
|
公开声明引用 Three.js 类型。`@types/three` 是 SDK 的开发依赖，不会随运行依赖传递，消费项目需自行安装。JavaScript 项目需要完整 JSDoc 提示时也可安装。
|
|
@@ -313,16 +316,17 @@ async function refreshModel() {
|
|
|
313
316
|
|
|
314
317
|
## 4. 组件参数
|
|
315
318
|
|
|
316
|
-
| Prop | 类型 | 默认值
|
|
317
|
-
| ------------------ | ------------------------- |
|
|
318
|
-
| `modelSource` | `ModelSource` | 必填
|
|
319
|
-
| `markers` | `Marker[]` | `[]`
|
|
320
|
-
| `initialView` | `InitialView` | `{}`
|
|
321
|
-
| `cameraTransition` | `CameraTransitionOptions` | `{ duration: 800 }`
|
|
322
|
-
| `gis` | `GisOptions` |
|
|
323
|
-
| `background` | `BackgroundOptions` | `{ color: '#f4f7fb' }`
|
|
319
|
+
| Prop | 类型 | 默认值 | 生效方式 |
|
|
320
|
+
| ------------------ | ------------------------- | ------------------------------------------------- | ------------------------------------------------- |
|
|
321
|
+
| `modelSource` | `ModelSource` | 必填 | 监听 `manifestUrl` 字符串变化，自动加载/重载 |
|
|
322
|
+
| `markers` | `Marker[]` | `[]` | 深度监听响应式标签数据，更新标签投影和显示 |
|
|
323
|
+
| `initialView` | `InitialView` | `{}` | 成功展示模型时交给渲染器，用于全模型适配与重置 |
|
|
324
|
+
| `cameraTransition` | `CameraTransitionOptions` | `{ duration: 800 }` | 定位和重置时读取，设置默认过渡时长 |
|
|
325
|
+
| `gis` | `GisOptions` | 不加载地图 | 可选天地图影像及 DEM，见 9.9、9.11 |
|
|
326
|
+
| `background` | `BackgroundOptions` | `{ color: '#f4f7fb' }` | 深度监听，实时更新背景，不重载模型 |
|
|
327
|
+
| `navigation` | `NavigationOptions` | `{ home: true, cube: true, componentTree: true }` | 构件目录、Home 与方向骰子分别实时显隐，不重载模型 |
|
|
324
328
|
|
|
325
|
-
Vue 模板中分别使用 `:model-source`、`:markers`、`:initial-view`、`:camera-transition`、`:gis` 和 `:
|
|
329
|
+
Vue 模板中分别使用 `:model-source`、`:markers`、`:initial-view`、`:camera-transition`、`:gis`、`:background` 和 `:navigation`。
|
|
326
330
|
|
|
327
331
|
`InitialView` 的字段：
|
|
328
332
|
|
|
@@ -333,7 +337,59 @@ Vue 模板中分别使用 `:model-source`、`:markers`、`:initial-view`、`:cam
|
|
|
333
337
|
|
|
334
338
|
非法或零方向使用默认方向；无效留白倍率使用默认值。`initialView` 没有独立的实时相机更新监听，不应当作相机控制 API；替换该配置后，可通过 `reload()` 在下一次成功展示时重新应用。`focusComponent()` 保持当前观察方向，`resetView()` 按当前渲染器持有的初始配置适配整个模型。
|
|
335
339
|
|
|
336
|
-
|
|
340
|
+
<a id="navigation"></a>
|
|
341
|
+
|
|
342
|
+
### 4.1 构件目录、Home 与 26 方向导航骰子
|
|
343
|
+
|
|
344
|
+
`NavigationOptions` 包含 `home?: boolean`、`cube?: boolean` 和 `componentTree?: boolean`，未提供的字段均为 `true`。可以替换整个配置，也可修改响应式对象的字段；界面立即生效，不重载模型、不改变当前相机。
|
|
345
|
+
|
|
346
|
+
| 配置 | 导航显示 |
|
|
347
|
+
| ---------------------------------------------------- | ------------------------------------------- |
|
|
348
|
+
| 不传、`{}` | 构件目录按钮、Home 与骰子均显示 |
|
|
349
|
+
| `{ home: false }` | 构件目录按钮与骰子 |
|
|
350
|
+
| `{ cube: false }` | 构件目录按钮与 Home，右上角收缩为 44px 按钮 |
|
|
351
|
+
| `{ componentTree: false }` | Home 与骰子，构件目录关闭并隐藏 |
|
|
352
|
+
| `{ home: false, cube: false, componentTree: false }` | 全部隐藏，不占位；实例方法仍可使用 |
|
|
353
|
+
|
|
354
|
+
```vue
|
|
355
|
+
<script setup>
|
|
356
|
+
import { reactive, shallowRef } from 'vue'
|
|
357
|
+
import { MineViewer } from '@caojinyu111/vue-bim-viewer'
|
|
358
|
+
import '@caojinyu111/vue-bim-viewer/style.css'
|
|
359
|
+
const viewer = shallowRef(null)
|
|
360
|
+
const source = { manifestUrl: '/models/manifest.json' }
|
|
361
|
+
const navigation = reactive({ home: true, cube: true, componentTree: true })
|
|
362
|
+
</script>
|
|
363
|
+
|
|
364
|
+
<template>
|
|
365
|
+
<label><input v-model="navigation.home" type="checkbox" />Home</label>
|
|
366
|
+
<label><input v-model="navigation.cube" type="checkbox" />方向骰子</label>
|
|
367
|
+
<label><input v-model="navigation.componentTree" type="checkbox" />构件目录</label>
|
|
368
|
+
<div style="height: 600px">
|
|
369
|
+
<MineViewer ref="viewer" :model-source="source" :navigation="navigation" />
|
|
370
|
+
</div>
|
|
371
|
+
</template>
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
构件目录按钮位于左上角，距顶、左各 16px，命中区域 45px。面板默认关闭；打开后隐藏按钮，首次打开时面板左上角与按钮原位置重合。面板宽最多 320px、高最多 560px，尺寸受场景容器宽高减去 32px 的可用空间约束，列表独立滚动。模型就绪后默认展开根节点，仅呈现源模型实际层级，不含空间分类、地图、DEM 或标签。
|
|
375
|
+
|
|
376
|
+
标题文字及空白处显示四向移动光标，按住可用鼠标或触屏拖动面板；关闭按钮显示手形光标，不启动拖动。面板限制在场景内，四周保留 16px；打开和场景尺寸变化时自动修正并保存越界位置。关闭后按钮恢复原位，再次打开保留关闭前的位置。同一组件实例内，关闭、配置隐藏及模型重载均保留位置；重新挂载或刷新页面后恢复初始位置，不使用本地存储。搜索框和列表不作为拖动区域，拖动不触发模型旋转、平移或拾取。
|
|
377
|
+
|
|
378
|
+
目录搜索忽略名称大小写，保留匹配节点与祖先路径并自动展开；清除搜索恢复普通浏览的展开状态。搜索只过滤目录，不改变场景或复选框的操作范围。分支复选框按完整子树的几何体有效显隐显示全选、半选或未选，与颜色、透明度无关；没有几何后代的分支禁用复选框。取消勾选隐藏整组，勾选显示整组及此前单独隐藏的后代。单独显示隐藏祖先下的子构件会开启必要祖先，保留其他分支的隐藏状态。一次操作批量写入现有外观状态，沿用 `appearance-change`（`source: 'api'`）及外观保存、导入和恢复机制。
|
|
379
|
+
|
|
380
|
+
点击名称组合执行选择与定位：沿当前观察方向适配该分支的包围盒，沿用 `cameraTransition`，不自动寻找无遮挡方向。隐藏构件保持隐藏，只更新选择并定位；没有可定位几何时只选择并显示提示，相机不移动。公开 `selectComponent()` 和 `focusComponent()` 各自的行为保持独立。
|
|
381
|
+
|
|
382
|
+
三维拾取与宿主 API 选择会同步目录，面板打开时展开选中节点的祖先并滚动定位；选中项被当前搜索排除时保留搜索并提示。关闭面板或隐藏按钮保留显隐、选择及相机状态。成功切换模型后重置搜索、展开和选择；加载失败保留原模型与目录状态。目录不监听自定义键盘快捷键，Esc 不关闭面板；搜索框正常输入，展开按钮、复选框和名称按钮按原生焦点顺序及键盘行为工作。点击关闭后焦点返回目录按钮。目录鼠标操作不触发场景拾取或缩放。
|
|
383
|
+
|
|
384
|
+
视角导航位于右上角，距顶、右各 16px；骰子区域为 150×150px，Home 图标约 24px、命中区域 44px。切角骰子和房屋图标使用本地 SVG 和 Three.js 数学计算绘制，不请求远程素材。GIS 署名自动排列在右侧导航下方，标记弹窗避开右侧导航区域。
|
|
385
|
+
|
|
386
|
+
Home 等同于 `resetView()`：按 `initialView` 恢复方向，并重新适配整个模型，不清除选择、外观修改或标记。骰子随主相机旋转，六个面、十二条边、八个角均可点击；方向切换保留当前观察目标与距离，因此构件定位后仍围绕该构件观察。
|
|
387
|
+
|
|
388
|
+
世界坐标固定为上 `+Y`、下 `-Y`、右 `+X`、左 `-X`、前 `+Z`、后 `-Z`；边角方向是相应轴向量之和再归一化，不自动识别建筑正门。上下视角保留极小偏角，避免 OrbitControls 在极点退化。连续点击会从当前动画姿态转向新方向，主视窗拖动中断动画；时长沿用 `cameraTransition`，默认 800ms，减少动态效果设置下立即切换。
|
|
389
|
+
|
|
390
|
+
首次就绪前及图形上下文丢失后禁用导航；旧模型保留时重载期间仍可导航，失败后继续操作旧模型。控件支持 Tab、Enter、Space，点击不触发模型拾取。隐藏骰子时停止投影更新，再次显示立即同步当前朝向。此功能不包含骰子拖动、下拉菜单或实体 Home 键快捷操作；内部组件不从包入口导出。
|
|
391
|
+
|
|
392
|
+
### 4.2 背景颜色与背景图片
|
|
337
393
|
|
|
338
394
|
`BackgroundOptions` 为公开类型，可用 `import type { BackgroundOptions } from '@caojinyu111/vue-bim-viewer'` 引入：
|
|
339
395
|
|
|
@@ -421,25 +477,28 @@ function onBackgroundError(error) {
|
|
|
421
477
|
|
|
422
478
|
通过 `<MineViewer ref="viewer" />` 获取实例，再调用 `viewer.value` 上的方法。表中“未就绪”指尚无成功加载的模型；重载期间已有旧模型时，查询仍可返回旧模型的数据。
|
|
423
479
|
|
|
424
|
-
| 方法
|
|
425
|
-
|
|
|
426
|
-
| `getComponentTree()`
|
|
427
|
-
| `getSceneTree()`
|
|
428
|
-
| `getSceneRoot()`
|
|
429
|
-
| `getComponentId(node)`
|
|
430
|
-
| `getComponent(id)`
|
|
431
|
-
| `getComponentAnchor(id, anchor?)`
|
|
432
|
-
| `getComponentAppearance(id)`
|
|
433
|
-
| `setComponentAppearance(id, patch)`
|
|
434
|
-
| `setComponentAppearances(updates)`
|
|
435
|
-
| `getAppearanceChanges()`
|
|
436
|
-
| `applyAppearanceChanges(value)`
|
|
437
|
-
| `restoreComponent(id)`
|
|
438
|
-
| `restoreAllComponents()`
|
|
439
|
-
| `selectComponent(id)`
|
|
440
|
-
| `focusComponent(id, options?)`
|
|
441
|
-
| `resetView(options?)`
|
|
442
|
-
| `
|
|
480
|
+
| 方法 | 输入与默认值 | 返回值 | 未就绪、未知 ID 或其他边界 |
|
|
481
|
+
| --------------------------------------- | --------------------------------------- | ----------------------------- | ---------------------------------------------------------------------- |
|
|
482
|
+
| `getComponentTree()` | 无 | `ComponentTree \| null` | 未就绪为 `null`；返回完整独立快照 |
|
|
483
|
+
| `getSceneTree()` | 无 | `ComponentTree \| null` | 未就绪为 `null`；结构同源，去掉业务元数据，仅保留源节点索引关联 |
|
|
484
|
+
| `getSceneRoot()` | 无 | `Object3D \| null` | 未就绪为 `null`；返回 Loader 原始场景根，活对象、只读使用 |
|
|
485
|
+
| `getComponentId(node)` | 当前场景的 `Object3D` 引用 | `string \| null` | 未就绪或对象不属于当前场景为 `null` |
|
|
486
|
+
| `getComponent(id)` | 构件 ID 字符串 | `ComponentNode \| null` | 未知 ID/未就绪为 `null`；含该节点的后代快照 |
|
|
487
|
+
| `getComponentAnchor(id, anchor?)` | ID；`anchor` 默认 `'origin'` | `Point3 \| null` | 未知 ID/未就绪为 `null`；没有包围盒时只能查询原点 |
|
|
488
|
+
| `getComponentAppearance(id)` | ID | `AppearanceState \| null` | 未知 ID/未就绪为 `null` |
|
|
489
|
+
| `setComponentAppearance(id, patch)` | ID 和外观字段 | `OperationResult` | 未就绪返回 `error`；未知 ID/非法 patch 分别报告 |
|
|
490
|
+
| `setComponentAppearances(updates)` | `{ id, patch }[]` | `OperationResult` | 有效项应用，非法项跳过；不是整批回滚 |
|
|
491
|
+
| `getAppearanceChanges()` | 无 | `AppearanceChangeSet \| null` | 未就绪为 `null`；就绪但无修改时 `overrides: []` |
|
|
492
|
+
| `applyAppearanceChanges(value)` | 已解析的差异对象，不是 JSON 字符串 | `OperationResult` | 格式、版本、字段校验失败时不应用；未知 ID 单独报告 |
|
|
493
|
+
| `restoreComponent(id)` | 当前模型中的构件 ID | `OperationResult` | 只取消该节点自身覆盖；无效 ID 返回错误或 `unknownIds`，不修改外观 |
|
|
494
|
+
| `restoreAllComponents()` | 无 | `OperationResult` | 删除所有自身覆盖；未就绪返回 `error` |
|
|
495
|
+
| `selectComponent(id)` | ID 或 `null` | `boolean` | 有效选择/清空成功为 `true`；未知 ID/未就绪为 `false` |
|
|
496
|
+
| `focusComponent(id, options?)` | ID；可选 `{ duration }`，毫秒 | `boolean` | 接受定位为 `true`；未知 ID/未就绪/非法时长为 `false`；不自动选择 |
|
|
497
|
+
| `resetView(options?)` | 可选 `{ duration }`，毫秒 | `boolean` | 有模型时重置全模型视角；无模型/非法时长为 `false` |
|
|
498
|
+
| `setViewDirection(direction, options?)` | 六个标准方向；可选 `{ duration }`，毫秒 | `boolean` | 保留观察目标与距离；未就绪、非法方向或时长返回 `false`，不打断有效动画 |
|
|
499
|
+
| `reload()` | 无 | `Promise<void>` | 取消前一轮加载；失败保留旧场景，通过事件报告结果 |
|
|
500
|
+
|
|
501
|
+
`ViewDirection` 为 `'top' | 'bottom' | 'left' | 'right' | 'front' | 'back'`。例如 `viewer.value.setViewDirection('front', { duration: 0 })` 立即切到前视角。其余 20 个边角方向仅由内置骰子触发，不属于公开参数。
|
|
443
502
|
|
|
444
503
|
### 5.2 构件树、节点和版本
|
|
445
504
|
|
|
@@ -490,7 +549,7 @@ function inspectComponents(api) {
|
|
|
490
549
|
|
|
491
550
|
### 5.4 模型坐标和锚点
|
|
492
551
|
|
|
493
|
-
SDK 使用加载后源场景的模型坐标，展示居中通过外层 wrapper
|
|
552
|
+
SDK 使用加载后源场景的模型坐标，展示居中通过外层 wrapper 实现，不改写节点数据。模型点和节点坐标沿用源模型单位；glTF 通常以米为单位，但 SDK 不会根据尺寸自动猜测或换算单位。需要进行 GIS 配准时，通过 `metersPerUnit` 声明一个模型单位对应多少米。
|
|
494
553
|
|
|
495
554
|
| anchor | 返回位置 | 注意事项 |
|
|
496
555
|
| -------------- | --------------------------- | ----------------------------------------------------- |
|
|
@@ -511,7 +570,11 @@ function readAnchors(api, componentId) {
|
|
|
511
570
|
|
|
512
571
|
### 5.5 选择、定位与高级场景读取
|
|
513
572
|
|
|
514
|
-
`selectComponent(id)`
|
|
573
|
+
`selectComponent(id)` 设置选择效果并发出 `component-select`，不会自动移动相机；`focusComponent(id)` 调整视野但不会自动选择。空节点定位会围绕其原点给出局部视野。
|
|
574
|
+
|
|
575
|
+
选择样式由 SDK 内置：青绿色表面高亮与浅绿色细轮廓，保留纹理、明暗和原有透明度，遵循场景遮挡，不显示穿透轮廓、不闪烁，也不自动创建标签。选择父节点时作用于其可见且非完全透明的子网格；隐藏构件不显示高亮。三维点击、构件树调用及 API 选择使用同一效果，不提供样式修改或禁用参数。
|
|
576
|
+
|
|
577
|
+
切换选择或传入 `null` 清空时恢复构件当前外观。选中期间修改颜色、透明度、显隐或导入、恢复外观，均继续生效；临时高亮不修改共享源材质、不计入外观差异、不触发 `appearance-change`。业务标签保持独立，地图与 DEM 不参与构件选择。
|
|
515
578
|
|
|
516
579
|
定位和重置默认使用 800 毫秒缓入缓出动画。通过组件 `:camera-transition="{ duration: 1000 }"` 设置统一时长，单次调用优先使用传入的 `duration`：
|
|
517
580
|
|
|
@@ -594,7 +657,7 @@ function restoreEverything(api) {
|
|
|
594
657
|
}
|
|
595
658
|
```
|
|
596
659
|
|
|
597
|
-
**调用约束：`restoreComponent` 必须传入当前模型中的有效构件 ID
|
|
660
|
+
**调用约束：`restoreComponent` 必须传入当前模型中的有效构件 ID。漏传参数、传入 `undefined`、`null` 或空字符串会返回 `error`，不会修改任何外观；格式正确但不存在的 ID 会进入 `unknownIds`。需要恢复全部覆盖时，必须显式调用 `restoreAllComponents()`。**
|
|
598
661
|
|
|
599
662
|
`restoreComponent(id)` 在传入有效 ID 时不递归删除后代独立覆盖；需要全部恢复时使用 `restoreAllComponents()`。重复设置相同值或设置回逻辑初值可能不会产生新的差异。
|
|
600
663
|
|
|
@@ -843,6 +906,7 @@ function onMarkerClick(marker) {
|
|
|
843
906
|
| `appearance-change` | `AppearanceEvent` | 外观自身覆盖发生变化；包含 source、before、after 和 result |
|
|
844
907
|
| `marker-click` | `Marker` | 标签被点击，包括再次点击同一标签关闭弹窗时 |
|
|
845
908
|
| `gis-status` | `GisStatus` | 影像加载、部分失败、就绪、关闭或错误状态变化 |
|
|
909
|
+
| `terrain-status` | `TerrainStatus` | DEM 准备、部分失败、就绪、关闭或错误；与影像计数独立 |
|
|
846
910
|
| `background-error` | `{ message: string }` | 背景颜色/图片配置无效或当前图片加载失败；与模型错误独立 |
|
|
847
911
|
|
|
848
912
|
`AppearanceEvent.source` 为 `'api'`、`'restore'` 或 `'import'`；`before/after` 为 `AppearanceChangeSet` 快照，`result` 为本次 `OperationResult`。事件用于宿主同步界面和保存，不需要自行重新维护一套覆盖状态。
|
|
@@ -869,15 +933,15 @@ function onAppearanceChange(event) {
|
|
|
869
933
|
|
|
870
934
|
<a id="gis"></a>
|
|
871
935
|
|
|
872
|
-
## 9. GIS
|
|
936
|
+
## 9. GIS 配准、影像与 DEM
|
|
873
937
|
|
|
874
938
|
### 9.1 用途与基本流程
|
|
875
939
|
|
|
876
|
-
`createGisPlacement(options)` 是独立函数，无需先挂载 `MineViewer
|
|
940
|
+
`createGisPlacement(options)` 是独立函数，无需先挂载 `MineViewer`。默认 `least-squares` 模式输入三个或更多在水平面上分散且不共线的“原始模型点 ↔ 现实坐标”对应关系，保持模型尺寸和竖直方向，求水平旋转和平移；有高程时再拟合整体竖直偏移。使用 `first-point` 模式时，首个控制点固定水平位置，其余控制点用于确定方向，不要求满足最小二乘模式的分布条件，但不能与首点水平重合，且方向不能互相抵消。
|
|
877
941
|
|
|
878
942
|
推荐流程：确认现实坐标系和模型单位/竖直轴，选取分散的对应点，调用方法，检查逐点误差，再用未参与拟合的独立点复核，最后由宿主将结果接到 GIS 模型图层。
|
|
879
943
|
|
|
880
|
-
|
|
944
|
+
此函数只计算配准结果，不自动倾斜、拉伸模型，不自动识别坐标系，也不会直接修改 Viewer 场景。将结果传给 `gis` 组件属性可显示天地图影像，见 9.9；可选 DEM 地形见 9.11。
|
|
881
945
|
|
|
882
946
|
### 9.2 全部输入选项
|
|
883
947
|
|
|
@@ -899,22 +963,22 @@ function onAppearanceChange(event) {
|
|
|
899
963
|
| `EPSG:4490` | `{ longitude, latitude, height? }` | CGCS2000，经度、纬度均为度 |
|
|
900
964
|
| `EPSG:4326` | `{ longitude, latitude, height? }` | WGS84，经度、纬度均为度 |
|
|
901
965
|
|
|
902
|
-
模型点始终为 `{ x, y, z }
|
|
966
|
+
模型点始终为 `{ x, y, z }`，坐标单位沿用源模型单位；SDK 不会自动判断或换算米、毫米等单位。`metersPerUnit` 用于声明一个模型单位对应多少米。即使暂不做高程配准也要提供完整模型点；可省略的是地图点的 `height`。经纬度不是平面米制坐标，测量 X/Y 也不能直接填入 `longitude/latitude`。
|
|
903
967
|
|
|
904
|
-
### 9.3
|
|
968
|
+
### 9.3 测量控制点接入示例
|
|
905
969
|
|
|
906
|
-
本例以测量人员**已确认 EPSG:4529**
|
|
970
|
+
本例以测量人员**已确认 EPSG:4529** 为使用前提。表中坐标仅用于说明数据结构，实际接入时必须替换为项目测量结果；不能根据数字推断坐标系。三个控制点的模型对应点须从原始模型中取得，并与实际测量点一一对应，不能直接用对象原点或包围盒中心代替。
|
|
907
971
|
|
|
908
972
|
```js
|
|
909
973
|
import { createGisPlacement } from '@caojinyu111/vue-bim-viewer'
|
|
910
974
|
|
|
911
975
|
// modelPoints 的三项均须为真实原始模型坐标 { x, y, z }。
|
|
912
976
|
// ellipsoidHeights 为可选椭球高对象，键名与 modelPoints 一致。
|
|
913
|
-
function
|
|
977
|
+
function locateModel(modelPoints, ellipsoidHeights = {}) {
|
|
914
978
|
const surveys = [
|
|
915
|
-
['
|
|
916
|
-
['
|
|
917
|
-
['
|
|
979
|
+
['controlA', 4500000, 41500000],
|
|
980
|
+
['controlB', 4500000, 41500100],
|
|
981
|
+
['controlC', 4500100, 41500000],
|
|
918
982
|
]
|
|
919
983
|
const controlPoints = surveys.map(([key, northing, easting]) => ({
|
|
920
984
|
model: modelPoints[key],
|
|
@@ -934,12 +998,12 @@ function locateMine(modelPoints, ellipsoidHeights = {}) {
|
|
|
934
998
|
})
|
|
935
999
|
}
|
|
936
1000
|
|
|
937
|
-
function
|
|
938
|
-
const placement =
|
|
1001
|
+
function inspectPlacement(modelPoints, ellipsoidHeights) {
|
|
1002
|
+
const placement = locateModel(modelPoints, ellipsoidHeights)
|
|
939
1003
|
console.log('模型原点位置', placement.position)
|
|
940
1004
|
console.log('水平角度', placement.rotationDegrees)
|
|
941
1005
|
console.table(placement.residuals)
|
|
942
|
-
return placement.toGeographic(modelPoints.
|
|
1006
|
+
return placement.toGeographic(modelPoints.controlA)
|
|
943
1007
|
}
|
|
944
1008
|
```
|
|
945
1009
|
|
|
@@ -1042,7 +1106,8 @@ ENU 的轴顺序为东、北、上。Y 向上的模型在水平旋转前按 `(x,
|
|
|
1042
1106
|
| 少于 3 个点、缺模型/地图坐标 | 抛错，补全对应关系 |
|
|
1043
1107
|
| 未支持的 CRS 或不合法的 `modelUpAxis` | 抛错，明确坐标系及 Y/Z 竖直轴 |
|
|
1044
1108
|
| 非有限数字、超范围经纬度、非法单位比例 | 抛错，检查数字类型和单位 |
|
|
1045
|
-
|
|
|
1109
|
+
| `least-squares` 模式的模型或地图水平点共线、重合或过于接近共线 | 抛错，重新选择水平分散的点位 |
|
|
1110
|
+
| `first-point` 模式的其他控制点与首点水平重合 | 抛错，选择能够确定水平方向的点位 |
|
|
1046
1111
|
| EPSG:4529 的 easting 缺少 41 带号或轴序颠倒 | 抛错，按测量 X/Y 正确填 northing/easting |
|
|
1047
1112
|
| 不能确定一致的水平旋转 | 抛错，核对对应点 |
|
|
1048
1113
|
| 水平误差超过 `maxErrorMeters` | 抛错，排查点位/单位/坐标系；不设阈值时通过结果报告误差 |
|
|
@@ -1073,7 +1138,7 @@ const gis = {
|
|
|
1073
1138
|
|
|
1074
1139
|
应在构件树就绪后从当前模型取得控制点，并同步重建 `gis` 配置。上述 `fallbackHeight` 将第一个模型点对齐 ENU up=0，仅用于无高程时的平面预览。省略 `map.height` 时，`heightResolved` 保持 `false`。对象原点或包围盒中心不能代替现场确认的测量点。
|
|
1075
1140
|
|
|
1076
|
-
`gis` 接收 `GisOptions`：`enabled?` 默认 false，`placement` 为配准结果，`imagery.key` 由宿主传入，`opacity?` 默认 0.65，范围 0–1
|
|
1141
|
+
`gis` 接收 `GisOptions`：`enabled?` 默认 false，`placement` 为配准结果，`imagery.key` 由宿主传入，`opacity?` 默认 0.65，范围 0–1。影像通过 three-tile 的 TDTSource 加载 HTTPS 天地图 img_w，不含注记。范围为模型水平范围外扩 1000 米后覆盖到瓦片边界，优先 16 级，最多 256 张；没有相机动态 LOD 或无限地图漫游。DEM 默认关闭，此时逐顶点转换到局部 ENU，压平 up=0，再通过配准逆矩阵及展示偏移显示。可选 DEM 见 9.11；地图不进入构件树、拾取和外观差异。
|
|
1077
1142
|
|
|
1078
1143
|
`gis-status` 为 `GisStatus`，含 `status`、`loaded`、`failed`、`total`、可选 `message`。status 为 `disabled/loading/ready/partial/error`。部分失败保留成功瓦片，全失败也不影响模型；无自动重试，可关闭再打开。透明度变化不重请求；关闭、替换配准/Key、模型成功切换和销毁会取消旧请求并释放纹理、ImageBitmap、材质和网格。相机聚焦仍以模型/构件为目标，远裁剪面兼顾地图。Key 在浏览器请求中可见，勿当作浏览器端秘密。
|
|
1079
1144
|
|
|
@@ -1154,6 +1219,52 @@ function onGisStatus(status) {
|
|
|
1154
1219
|
|
|
1155
1220
|
模型切换成功后会再次调用 `onReady`，使用新模型重建配准；配准失败时该例清空影像配置，模型仍可浏览。失败重载没有树就绪事件，保留旧模型及其原配准。示例锚点为中心，不等于真实测量点，实际控制点应使用现场确认的原始模型坐标。
|
|
1156
1221
|
|
|
1222
|
+
<a id="gis-terrain"></a>
|
|
1223
|
+
|
|
1224
|
+
### 9.11 可选 DEM 地形
|
|
1225
|
+
|
|
1226
|
+
`gis.terrain` 配置 DEM，默认关闭。相对预览配置如下，示例中的 `placement` 和 `tiandituKey` 由宿主提供：
|
|
1227
|
+
|
|
1228
|
+
```js
|
|
1229
|
+
const gis = {
|
|
1230
|
+
enabled: true,
|
|
1231
|
+
placement,
|
|
1232
|
+
imagery: { key: tiandituKey },
|
|
1233
|
+
opacity: 0.65,
|
|
1234
|
+
terrain: { enabled: true, mode: 'relative' },
|
|
1235
|
+
}
|
|
1236
|
+
// <MineViewer :gis="gis" @gis-status="onImagery" @terrain-status="onTerrain" ... />
|
|
1237
|
+
```
|
|
1238
|
+
|
|
1239
|
+
| 字段 | 类型 | 默认值及要求 |
|
|
1240
|
+
| ------------------- | --------------------------------------------------- | ------------------------------------------- |
|
|
1241
|
+
| `enabled` | `boolean` | 默认 `false`；需同时开启 `gis.enabled` |
|
|
1242
|
+
| `key` | `string` | 省略时复用 `gis.imagery.key` |
|
|
1243
|
+
| `mode` | `'relative' \| 'absolute'` | 默认 `'relative'` |
|
|
1244
|
+
| `toEllipsoidHeight` | `(point: Required<GeographicCoordinate>) => number` | `absolute` 模式必填，同步返回有限米制椭球高 |
|
|
1245
|
+
|
|
1246
|
+
相对模式以 `placement.reference` 处 DEM 为基准，其他点取高程差；参考点位于 ENU 零高程平面，水平位置不变。基准缺测则整层保留平面；此模式不证明井口与实际地表已经对齐。
|
|
1247
|
+
|
|
1248
|
+
真实高程需要 `placement.heightResolved === true`，并显式提供同步转换函数。以下 `terrain` 对象应作为 `gis.terrain` 传入；`convertDemToPlacementEllipsoid` 由宿主根据已确认的高程基准实现：
|
|
1249
|
+
|
|
1250
|
+
```js
|
|
1251
|
+
const terrain = {
|
|
1252
|
+
enabled: true,
|
|
1253
|
+
mode: 'absolute',
|
|
1254
|
+
toEllipsoidHeight({ longitude, latitude, height }) {
|
|
1255
|
+
return convertDemToPlacementEllipsoid(longitude, latitude, height)
|
|
1256
|
+
},
|
|
1257
|
+
}
|
|
1258
|
+
```
|
|
1259
|
+
|
|
1260
|
+
输入 `height` 是天地图 DEM 原始米制高程，返回值必须是与配准一致的有限 `number` 椭球高（米），不能返回 `null`、布尔值、字符串或 Promise。只有确认基准一致时才能直接返回 height；正常高需要可靠的大地水准面/似大地水准面转换。SDK 不推断基准，也不将人工常数偏移当作通用转换。配置缺失、回调抛错、返回非数字或非有限值时报告错误并保留相应平面影像，不悄悄切换相对模式。真实模式使用完整 ECEF → ENU → 配准逆变换 → 展示偏移；模型和 Marker 坐标始终不变。
|
|
1261
|
+
|
|
1262
|
+
SDK 的天地图 `elv_c` 适配器支持 zlib 压缩的 150×150 小端 UInt16 高程栅格，采用独立的地理 c 瓦片矩阵和三角插值，不直接复用影像 w 矩阵行列。DEM 数据级别取影像级别与 12 的较小值，影像级别 6 以下报告不支持地形；这是 SDK 的数据级别限制，不保证服务在所有区域和级别均有有效数据。每张影像生成 33×33 地表顶点及独立向下裙边，共享边缘取样一致。缺测值不伪造成零，相机缩放不改变瓦片级别，不支持地形碰撞或自动贴地，模型地表构件不会自动隐藏。
|
|
1263
|
+
|
|
1264
|
+
`TerrainStatus` 包含 `status`、`mode`、`loaded`、`failed`、`total` 和可选 `message`。状态为 disabled/loading/ready/partial/error，计数表示目标影像瓦片的 DEM 准备成功/失败数，而非网络请求数；影像和 DEM 分别报告结果。单块失败保留平面，全部失败仍可浏览影像与模型。未知高程基准只能使用相对预览。
|
|
1265
|
+
|
|
1266
|
+
影像先以平面显示，地形准备成功后替换网格；材质支持透明度、双面及地下观察。影像与 DEM 合计最多 6 个在途请求，每请求 15 秒超时，无自动重试，DEM 按实例去重并采用 64 MiB 缓存。透明度不触发新请求；改变模式、配准、Key 或转换函数引用会重建图层。请使用稳定的转换函数引用。关闭、切换模型和销毁会取消请求并清空缓存，迟到结果不回到场景。浏览器缺少 DEM 解压能力时地形失败但保留影像。
|
|
1267
|
+
|
|
1157
1268
|
<a id="types"></a>
|
|
1158
1269
|
|
|
1159
1270
|
## 10. 公开类型索引
|
|
@@ -1184,14 +1295,18 @@ function onGisStatus(status) {
|
|
|
1184
1295
|
| `MarkerOverlay` | 投影标签数组、issues、视口宽高；内部布局数据的公开类型，无独立查询方法 | [标签](#markers) |
|
|
1185
1296
|
| `ModelInfo` | 模型身份、名称、URL、统计、warnings | [加载事件](#model-loading) |
|
|
1186
1297
|
| `SceneAssociation` | 可选 `nodes` 源节点索引，Loader 关联辅助类型，无独立查询方法 | [场景读取](#viewer-api) |
|
|
1187
|
-
| `
|
|
1298
|
+
| `NavigationOptions` | `home?`、`cube?`、`componentTree?`，均默认 true | [导航](#navigation) |
|
|
1299
|
+
| `ViewDirection` | 六个标准观察方向 | [导航](#navigation) |
|
|
1300
|
+
| `ViewerApi` | 组件 ref 暴露的 18 个方法 | [实例方法](#viewer-api) |
|
|
1188
1301
|
| `GeographicCoordinate` | `longitude`、`latitude`、`height?` | [GIS](#gis) |
|
|
1189
1302
|
| `SurveyCoordinate` | `northing`、`easting`、`height?` | [GIS](#gis) |
|
|
1190
1303
|
| `GisControlPoint<T>` | `{ model: Point3, map: T }`，T 默认 GeographicCoordinate | [GIS](#gis) |
|
|
1191
1304
|
| `GisPlacementOptions` | 配准输入，CRS 决定地图点类型 | [GIS](#gis) |
|
|
1192
1305
|
| `GisPlacement` | 配准矩阵、位置、误差及坐标转换方法 | [GIS](#gis) |
|
|
1193
|
-
| `GisOptions` |
|
|
1306
|
+
| `GisOptions` | 可选影像与 DEM 配置，Key/配准/开关/透明度 | [GIS](#gis) |
|
|
1194
1307
|
| `GisStatus` | 图层状态、瓦片计数与可选错误消息 | [GIS](#gis) |
|
|
1308
|
+
| `TerrainOptions` | 相对预览或真实高程模式，独立 Key 与高程转换函数 | [GIS](#gis) |
|
|
1309
|
+
| `TerrainStatus` | 独立 DEM 状态、模式、目标瓦片准备计数及错误消息 | [GIS](#gis) |
|
|
1195
1310
|
|
|
1196
1311
|
`ModelMetadata`、`LoadedModel`、内部 `createViewer()` 等即使在源码文件中导出，也没有从 package 根入口公开，不作为宿主可直接导入的稳定 API。消费项目应通过包名和公开样式入口接入，不依赖源码路径或未声明的包子路径。
|
|
1197
1312
|
|
|
@@ -1203,8 +1318,8 @@ function onGisStatus(status) {
|
|
|
1203
1318
|
|
|
1204
1319
|
安装包包含构建产物、公开类型声明、README、API 文档和许可证。消费项目通过包名及以下子路径接入，不依赖 SDK 源码或构建脚本：
|
|
1205
1320
|
|
|
1206
|
-
| 入口
|
|
1207
|
-
|
|
|
1321
|
+
| 入口 | 用途 |
|
|
1322
|
+
| ------------------------------------------ | ---------------------------------- |
|
|
1208
1323
|
| `@caojinyu111/vue-bim-viewer` | ESM/CJS 运行导出与 TypeScript 声明 |
|
|
1209
1324
|
| `@caojinyu111/vue-bim-viewer/style.css` | 组件样式，由应用前端构建工具处理 |
|
|
1210
1325
|
| `@caojinyu111/vue-bim-viewer/package.json` | 包信息 |
|
|
@@ -1236,6 +1351,7 @@ const {
|
|
|
1236
1351
|
| 现象 | 优先检查 |
|
|
1237
1352
|
| ----------------------------- | ---------------------------------------------------------------------------------- |
|
|
1238
1353
|
| 页面没有三维内容 | 父容器是否有非零宽高、是否引入样式、浏览器 WebGL2 是否可用、model-error 内容 |
|
|
1354
|
+
| 地图没有加载 | GIS 是否启用、浏览器是否支持 `fetch`、`createImageBitmap`、`AbortSignal.any`、`AbortSignal.timeout` 和 `OffscreenCanvas` |
|
|
1239
1355
|
| 模型加载失败 | Manifest version、entry 后缀、HTTP 状态、CORS、地址是否实际返回 HTML、外部资源路径 |
|
|
1240
1356
|
| 模型能显示但属性缺失 | model-loaded.warnings、元数据格式、源名称是否唯一、源节点关联是否存在 |
|
|
1241
1357
|
| ref 有值但查询为 null | 模型尚未成功就绪；在 component-tree-ready 后查询 |
|
|
@@ -1257,19 +1373,19 @@ const {
|
|
|
1257
1373
|
|
|
1258
1374
|
当前支持标准非压缩 GLB/glTF；没有在 Loader 中配置 Draco、KTX2、Meshopt 解码器，也不直接加载 IFC、RVT 等源 BIM 格式。当前包没有模型编辑、任意相机控制、动画播放、裁剪剖切、距离测量或业务模拟等公开能力。
|
|
1259
1375
|
|
|
1260
|
-
Marker 使用 DOM 标签，没有海量标签布局优化；GIS 方法提供定位计算，SDK
|
|
1376
|
+
Marker 使用 DOM 标签，没有海量标签布局优化；GIS 方法提供定位计算，SDK 支持可选有限范围的天地图影像及 DEM 地形（见 9.11），不加载注记或其他 GIS 引擎。新增需求应先区分是接入层业务功能，还是需要扩展 SDK 的公开能力。
|
|
1261
1377
|
|
|
1262
1378
|
### 12.1 实际适用范围
|
|
1263
1379
|
|
|
1264
|
-
适合 Vue 3 网页中的静态三角网格 BIM
|
|
1380
|
+
适合 Vue 3 网页中的静态三角网格 BIM 浏览、构件树查询、按节点选择/外观、业务标签，以及有限区域的 GIS 配准、天地图影像与 DEM 地形。IFC/RVT 等需要先在外部转换成标准非压缩 GLB/glTF。没有配置 Draco、KTX2、Meshopt 解码器；动画、编辑、测量、剖切不在当前公开能力内。InstancedMesh 按对象视为一个构件，不支持逐实例拾取与外观。Line/Points 不属于完整支持的构件外观与包围盒对象。
|
|
1265
1381
|
|
|
1266
|
-
GIS 仅接受 EPSG:4529、4490、4326
|
|
1382
|
+
GIS 仅接受 EPSG:4529、4490、4326，采用局部水平刚性配准和已知单位换算，不自动拟合缩放或精密基准转换。DEM 默认关闭，不支持注记和无限漫游；真实高程模式需提供可靠高程配准及基准转换，测量使用前需以真实控制点、残差和独立检查点验收。
|
|
1267
1383
|
|
|
1268
1384
|
### 12.2 已知问题与调用约束
|
|
1269
1385
|
|
|
1270
1386
|
| 项目 | 影响与建议 |
|
|
1271
1387
|
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1272
|
-
| 恢复构件的参数 | `restoreComponent
|
|
1388
|
+
| 恢复构件的参数 | `restoreComponent` 必须传入当前模型中的有效 ID；漏传或空 ID 返回 `error`，未知 ID 返回 `unknownIds`，全部恢复使用 `restoreAllComponents()`。 |
|
|
1273
1389
|
| 特殊对象的资源释放 | 释放以 Mesh 为主，Line/Points、Skeleton 骨骼纹理及 InstancedMesh 自身资源的 dispose 钩子覆盖不完整。反复加载此类模型可能累积 GPU 资源。 |
|
|
1274
1390
|
| Line/Points 外观 | 状态更新可能返回成功，但颜色、透明度及包围盒不具备完整支持；应使用静态 Mesh 模型。 |
|
|
1275
1391
|
| 外观更新成本 | 每次修改会同步扫描节点，已克隆材质可能重复更新；大模型和高频批量修改需结合实际业务压测。 |
|