3D 交互控件

「3D 交互」把已保存的户型作为可以旋转、切换楼层和操作设备的 3D 面板。你可以在户型里点灯、查看空调和窗帘、打开摄像头画面，并调整设备聚焦视角。

先完成一盏灯的配置，再逐步加入其他设备，会更容易检查模型、实体和画面是否对应。

阅读截图

截图展示现有项目的配置示例，模型名称、参数与实体请按自己的设备选择。

开始前准备

• 当前授权已开通 3D 交互功能增量包。控件提示未开通或授权失效时，先检查授权状态。
• 已在「户型图绘制」中完成并保存户型。还没绘制时，先看素材与 3D 户型图。
• 需要控制的灯组和设备模型已放到对应楼层，例如灯组、空调、窗帘、电视、扫地机器人和摄像头。
• Home Assistant 已连接，相关设备、实体能在 HA Bridge 中选择。先在 Home Assistant 确认设备状态与控制正常。

模型负责位置和外观，实体负责真实状态和控制。 在户型里放入一台空调后，还需要把它与家里对应的空调实体绑定。

1. 添加控件，载入户型

1. 打开目标仪表盘，选择要放置控件的「主页面」。
2. 点击「＋ 添加控件」，在模板库中选择「3D 交互」。
3. 等待已保存的户型载入。未保存户型时，先回到绘制页面保存，再重试。
4. 选中控件，在右侧「户型与布局」选择「自由」或「铺满」。自由布局可设置位置、宽高；铺满用于让 3D 面板覆盖画布。

载入后，可以在控件里选择楼层，右侧「设备配置」提供灯光、环境、设备、扫地机和安防入口。

2. 调整默认视角和导航

在右侧展开「视角与导航」：

1. 选择「视角楼层」，先确定调整的是某一层还是全部楼层。
2. 点击「调整户型视角」，在画面中旋转、平移和缩放。
3. 构图合适后点击「完成并固定」，保留这个楼层的默认视角；不满意则点击「取消本次调整」。
4. 按需要调整楼层编号、全部楼层的间距，以及分类栏、楼层栏的位置和缩放。

配置窗口里拖动空白处可旋转，右键平移、滚轮缩放。临时查看不会替代已经固定的视角；需要保存视角时，应进入对应的视角调整步骤。

3. 配置第一盏灯

关联灯组和实体

1. 在「设备配置」点击「配置灯光」。
2. 选择「配置楼层」，点击「添加灯光」。
3. 在「关联灯组」选择绘制时建立的灯组，点击「确定添加」。
4. 在「基础绑定」填写名称，并通过「绑定实体」选择对应的灯或开关。

如果没有可添加的灯组，先在「户型图绘制」中添加并保存灯组，再回到控件检查。

选择点击行为

「点击灯光」决定点按户型里的灯光按钮时做什么：

选项	使用效果
仅聚焦	把视角移到这盏灯附近。
聚焦并开灯	聚焦到灯光，同时执行开灯。
仅开关灯	直接切换灯光开关。
开灯并弹窗	开灯并显示控制弹窗。

按需调整按钮图标、大小、点击范围、位置和高度。「隐藏（可点击）」保留点击区域；「隐藏（不可点击）」同时禁用该按钮的点击。

需要指定聚焦画面时，在「聚焦视角」点击「设置视角」，调整后保存，并用「预览聚焦」检查效果。

调整照射范围

点击「编辑照射范围」，在独立窗口中设置：

• 平面编辑：选择楼层和灯具，拖动边角调整范围，设置形状、宽度、深度、旋转与边缘柔和度。
• 3D 预览：检查高度效果；「最低照到」「最高照到」从本层地面开始计算，留空使用自动值。
• 要移动光区中心，先打开「允许移动范围中心」；同一灯组有多个范围时，可按需要使用「同步本组范围」。

范围边界表示光照衰减到零的位置，不代表墙体挡光。调整好后先保存范围，再点击灯光窗口顶部的「保存配置」。

亮度、色温和批量应用

在「灯光效果」设置默认亮度、色温和效果范围；具体可控制的项目取决于绑定实体的能力。只有开关能力的实体不会因为配置了色温就变成可调色温设备。

同类灯光需要相同外观时，可用「一键应用到其他灯光」，勾选要应用的设置和目标灯光，再保存配置。各灯光仍使用自己的实体绑定。

4. 添加环境和其他设备

其他设备沿用相同顺序：选择楼层 → 添加模型 → 绑定设备或实体 → 设置按钮和点击行为 → 保存配置。

配置入口	设备类型	绑定时注意
配置环境	空调、窗帘	先选择「环境类别」；空调关联温控实体，窗帘关联对应窗帘实体。
配置设备	电视、NAS	添加时选择设备类型与模型；电视选择媒体播放器，NAS 可选择整台飞牛或群晖作为状态来源。
配置扫地机	扫地机器人	选择模型后绑定扫地机设备，按可用数据配置聚焦、跟随和快捷指令。
配置安防	摄像头、人体传感器	选择安防类别及对应模型，再绑定摄像头实体或人体传感器设备。

空调与窗帘

打开「配置环境」，选择空调或窗帘，在当前楼层添加对应模型并绑定实体。设置点击后的聚焦或弹窗方式，再检查真实状态是否对应。

模型列表为空时，先检查该楼层是否已经放入对应模型。窗帘布类型跟随户型模型，需要在绘制页面调整。

电视、NAS 与扫地机

电视绑定媒体播放器实体，按实际接入能力设置电源和控制内容。NAS 选择数据来源后可调整显示指标；其状态弹窗用于查看 CPU、内存、温度、存储与网络等信息。

图中示例单独绑定了电视电源实体，媒体播放器尚未选择；需要节目封面等内容时，再绑定对应的媒体播放器。

扫地机可设置聚焦视角、跟随视角和快捷按钮；「跟随真实位置移动」需要设备提供可用的位置数据。能看见扫地机模型，不代表已经完成实体绑定或具备实时定位。

摄像头与人体传感器

「配置安防」里选择摄像头或人体传感器，添加该楼层模型并绑定数据来源。摄像头可配置标签和聚焦视角；人体传感器优先选择整台设备，系统会匹配检测来源，也可在高级设置中调整触发条件。

人体传感器还可调整感应光圈大小与透明度，并在「配置人物与行走路线」中设置人物、显示时长与路线。

摄像头画面要先能在 Home Assistant 中正常播放，再在目标手机或平板上检查播放效果。

5. 画面效果、弹窗与交互

画面效果

先用默认设置检查整体，再逐项调整：

设置	用途
灯光模式	在「标准光影」和「轻量柔光」之间选择。
户型渲染	调整整体基础光照与模型呈现。
渲染分辨率	提高清晰度或降低设备负载。
转动分辨率	单独控制旋转过程中的画质。
地面反射	调整反射范围、清晰度和强度。
页面压暗、聚焦效果	调整不同分类页面和聚焦时的明暗层次。

手机或平板卡顿时，先降低渲染分辨率、转动分辨率与反射清晰度，再检查实际设备效果。

弹窗大小与位置

展开「弹窗大小与位置」，分别设置「通用弹窗」和「摄像头弹窗」。可调整大小、启用自定义位置，并点击「预览」直接检查。空间不足时会自动缩小；恢复默认可回到初始大小和位置。

通用预览使用窗帘示例，摄像头预览使用 16:9 示例；用于检查布局，实际内容与高度随设备变化。

自动旋转和闲置行为

展开「交互行为」，先选「全部页面」或「单页面」的设置范围，再配置：

• 旋转方式：自由、仅左右、仅上下；
• 自动旋转：等待时间、方向、速度，以及旋转前是否回到默认视角；
• 闲置时退出聚焦、闲置后隐藏图标、旋转时隐藏图标。

这里的「单页面」指 3D 控件内部的分类页面，例如灯光、环境、设备等。未单独设置的参数沿用「全部页面」。

6. 保存并在设备上验证

1. 在每个配置窗口点击「保存配置」，再退出窗口。
2. 回到编辑器，点击顶部「保存」，保存仪表盘。
3. 切换到「仪表盘」模式，依次检查楼层切换、默认视角、按钮位置、聚焦和弹窗。
4. 用一台真实设备验证开关或调节动作，确认状态会同步回来。
5. 按连接中控设备的教程在手机或平板打开，检查触控、旋转与摄像头播放。

建议先验证一盏灯和一个设备，确认绑定关系正确后再批量配置。

常见问题

看不到户型，或一直等待载入

确认绘制页面的户型已保存，3D 交互授权正常。载入失败时，在「户型与布局」使用「重新载入户型」重试。

添加列表里没有我要的设备

先确认配置楼层，再检查绘制页面中是否有对应类型的模型或灯组，以及是否已被当前配置关联。新加模型后先保存户型，再返回配置页面检查；删除或替换模型后，注意「原模型已移除，请重新选择」提示。

能看到模型，但点击没有控制设备

检查实体绑定和点击行为。「仅聚焦」只移动视角，不开关设备。实体不可用时，先检查 Home Assistant 连接和设备本身。

设置后刷新又恢复了

检查是否完成了两次保存：配置窗口的「保存配置」，以及编辑器顶部的「保存」。视角调整还需要点击「完成并固定」或对应的视角保存按钮。

桌面正常，平板卡顿或摄像头不播放

先降低画质，并在目标设备逐项检查。3D 性能和视频播放取决于硬件、浏览器及视频格式，桌面上的效果不能代替手机和平板验证。