soonspacejs-ustudio-plugin

基于 SoonSpaceJS 的 UStudio 场景工具插件，提供视图模式切换、楼层管理、标签、轮廓线、可达性路线等功能。

安装

npm install soonspacejs-ustudio-plugin
# 或
pnpm add soonspacejs-ustudio-plugin

soonspacejs 为 peerDependency，需单独安装。

部分 TypeScript 类型可从包中导出，例如：PluginOptions、ViewModeParams、TreeNode、SetSemantic2dOutlinesParams、ClearSemantic2dOutlinesParams、SemanticOutline2DType 等（见 src/index.ts 与 src/types.ts）。

本地跑 pnpm dev:example 前请先 pnpm build：仓库内示例从 dist/index.js 引用插件，与 npm 安装后的用法一致，不直接依赖 src/ 源码路径。

快速上手

方式一：registerPlugin 注册

import SoonspaceUStudioPlugin from 'soonspacejs-ustudio-plugin'

const plugin = ssp.registerPlugin(SoonspaceUStudioPlugin, 'ustudio', {
  yExtendSpacing: 200,
})

方式二：直接实例化

import { SoonspaceUStudioPlugin } from 'soonspacejs-ustudio-plugin'

const plugin = new SoonspaceUStudioPlugin(ssp, {
  yExtendSpacing: 200,
})

配置项（PluginOptions）

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | yExtendSpacing | number | 5 | YExtend 模式下楼层之间的 Y 轴间距 | | wall2dFootprintLineColor | number | 0x888888 | 2D 下自动墙轮廓线（LineLoop）颜色 | | wall2dFootprintLineWidth | number | 2 | 墙线线宽 | | window2dFootprintLineColor | number | 0x2196f3 | 2D 下窗轮廓线颜色 | | door2dFootprintLineColor | number | 0xffb300 | 2D 下门轮廓线颜色 | | opening2dFootprintLineWidth | number | 与墙线相同 | 门窗轮廓线宽 | | space2dPanelColor | number | 0x888888 | 2D 模式下 Space 水平投影半透明填充面颜色（灰） | | space2dPanelOpacity | number | 0.28 | Space 面板不透明度（0～1） | | space2dLineColor | number | — | 已废弃；未传 space2dPanelColor 时作为面板颜色回退 | | space2dLineWidth | number | — | 已废弃；Space 不再绘制轮廓线 | | story2dPlaneOpacity | number | — | 已废弃，保留仅为兼容旧配置 |

API

setViewMode(params, treeData)

切换场景视图模式，每次调用前自动重置所有变换。

await plugin.setViewMode(params: ViewModeParams | ViewModeParams[], treeData: TreeNode[])

ViewModeParams：

| 字段 | 类型 | 说明 | |------|------|------| | type | '3D' \| '2D' \| 'YExtend' | 模式类型 | | ids | string[] | 指定作用的 Story out_instance_id，不传则作用于全部楼层 | | hideWalls | boolean | 仅 3D 模式有效，隐藏墙体 | | hideWindowAndDoor | boolean | 仅 3D 模式有效，隐藏门窗 |

模式说明：

• 3D — 恢复正常三维视图；可配合 hideWalls / hideWindowAndDoor 隐藏构件
• 2D — 将楼层压扁为平面，Window/Door 着色标注（窗蓝、门黄）；自动绘制墙/门/窗轮廓线及 Space 灰色半透明水平投影面板（见 space2dPanelColor / space2dPanelOpacity）
• YExtend — 按楼层顺序在 Y 轴展开，间距由 yExtendSpacing 控制

多个模式可以组合传入数组同时生效：

// 2D 模式 + 楼层展开
await plugin.setViewMode([{ type: '2D' }, { type: 'YExtend' }], [treeData])

// 仅对 1F 显示 2D，其余楼层保持 3D
await plugin.setViewMode(
  [{ type: '2D', ids: [STORY_1F_ID] }, { type: '3D', ids: [STORY_2F_ID] }],
  [treeData]
)

// 3D 模式隐藏墙体和门窗
await plugin.setViewMode({ type: '3D', hideWalls: true, hideWindowAndDoor: true }, [treeData])

showTwinsNameLabels(treeData?, out_instance_ids?, storyIds?)

在树节点对应位置显示 twins_instance_name 标签；类型由树数据推断（按 out_instance_id 查节点，使用其 twins_identifier）。

• 未传 treeData（undefined/null）或 treeData 为空数组：直接返回。
• 未传 out_instance_ids 或为空数组：直接返回（不能只按楼层展示，必须给出实例 id 列表）。
• treeData + out_instance_ids：按 id 展示；可再传 storyIds，只保留落在这些楼层上的实例。

plugin.showTwinsNameLabels() // 无 treeData → return
plugin.showTwinsNameLabels([treeData]) // 无 out_instance_ids → return
plugin.showTwinsNameLabels([treeData], ['uuid-building', 'uuid-story'])
plugin.showTwinsNameLabels([treeData], ['uuid-a', 'uuid-b'], [STORY_1F_ID])

hideTwinsNameLabels(treeData?, out_instance_ids?, storyIds?)

移除文字标签。

• 不传 out_instance_ids 且 不传 storyIds：清空全部（可写 hideTwinsNameLabels()，不必传 treeData）。
• 仅 storyIds：移除这些楼层上已登记的全部标签。
• out_instance_ids：移除对应实例（可与 storyIds 组合）。

plugin.hideTwinsNameLabels()
plugin.hideTwinsNameLabels([treeData])
plugin.hideTwinsNameLabels([treeData], ['uuid-window-1'])
plugin.hideTwinsNameLabels([treeData], undefined, [STORY_1F_ID])

hideStories(treeData, ids?)

隐藏楼层。不传 ids 则隐藏全部楼层。

plugin.hideStories([treeData])              // 隐藏全部
plugin.hideStories([treeData], [STORY_1F_ID]) // 仅隐藏 1F

showStories()

恢复所有通过 hideStories 隐藏的楼层。

getVisibleStoryIds(treeData)

返回当前可见楼层的 out_instance_id 列表。

setSemantic2dOutlines(treeData, params)

控制 2D 语义轮廓线（墙/门/窗的水平投影 LineLoop），与 setViewMode 进入 2D 时自动绘制的线为同一套存储，用于显隐门窗线、墙线等。

plugin.setSemantic2dOutlines([treeData], {
  types: ['Wall', 'Window', 'Door', 'Space'], // 要操作的类型，空数组则直接 return
  story: [],                         // Story 的 out_instance_id；[] 表示全部楼层
  visible: true,                     // true 绘制，false 移除对应类型在指定楼层下的线
})

| params 字段 | 说明 | |---------------|------| | types | 'Wall' \| 'Window' \| 'Door' \| 'Space' 中需要绘制或移除的类型 | | story | 楼层 out_instance_id 列表；空数组表示全部楼层 | | visible | true 绘制；false 仅移除（不影响未列出的类型/楼层） |

clearSemantic2dOutlines(treeData?, params?)

清除 2D 语义墙/门窗线及 Space 面板（与 setSemantic2dOutlines 同一存储）。

• 无参数：清空当前已登记的全部墙/门/窗线及 Space 面板（全局，不依赖树）。
• treeData + 可选 params：按树与条件清除。
  • params.storyIds：不传或 [] 表示全部楼层。
  • params.types：不传或 [] 表示 Wall、Window、Door、Space 全部类型都清。
• 若未传 treeData，却又传了非空的 params.storyIds / params.types，方法会直接返回（无法按条件清除）。

plugin.clearSemantic2dOutlines() // 清除全部语义墙/门窗线及 Space 面板

plugin.clearSemantic2dOutlines([treeData]) // 按树清除全部楼层、全部类型

plugin.clearSemantic2dOutlines([treeData], {
  storyIds: [STORY_1F_ID],
  types: ['Window', 'Door'],
})

drawOutlineLines(treeData, lineType)

Wall/Window/Door 使用 topology 轴对齐矩形线；Space 使用 轴对齐半透明灰面板（与 setSemantic2dOutlines 的 LineLoop/面板不是同一套 API，用途不同）。

plugin.drawOutlineLines([treeData], 'Wall')   // 墙线（灰色）
plugin.drawOutlineLines([treeData], 'Window') // 窗线（青色）
plugin.drawOutlineLines([treeData], 'Door')   // 门线（橙色）
plugin.drawOutlineLines([treeData], 'Space')  // 空间：AABB 半透明面板（颜色/透明度同 `space2dPanelColor` 等）

clearOutlineLines(lineType?)

清除 drawOutlineLines 创建的 topology 线或 Space 面板。不传参数则清除全部类型。

drawReachableRoutes(edges, treeData, yExtend?)

绘制可达性路线。节点球贴在楼层地面，连线间有白色光点来回穿梭动画。

plugin.drawReachableRoutes(reachableData, [treeData])

// 楼层展开状态下绘制
plugin.drawReachableRoutes(reachableData, [treeData], true)

调用 setViewMode 时若已有活跃路线，会自动根据当前 YExtend 状态重绘。

ReachableEdge 数据结构：

interface ReachableEdge {
  edge_id: string
  start_out_instance_id: string  // 起点对象 ID
  end_out_instance_id: string    // 终点对象 ID
}

clearReachableRoutes()

清除可达性路线及动画。

TreeNode 数据结构

所有方法的 treeData 参数来自 CPS 平台 Digital Twin 树形数据，关键字段：

| 字段 | 说明 | |------|------| | twins_identifier | 语义类型：Building / Story / Wall / Window / Door / Space / Stairs 等 | | twins_instance_name | 实例名称；名称标签（showTwinsNameLabels）使用该字段 | | twins_name | 平台侧名称字段（与 twins_instance_name 可能并存） | | out_instance_id | BIM 实例 ID，对应 ssp.getObjectById(out_instance_id) | | children | 子节点，null 表示叶节点 |

License

MIT