认识控件及实体配置

控件是画布上的独立元素。添加前先确定放在侧边栏还是当前主页面，再在右侧设置实体、外观和动作。未绑定实体的控件可用于图片、标题或导航，但不能显示设备状态。

添加控件的固定顺序

1. 在左侧选择目标页面，或切换到「侧边栏」。
2. 点击「＋ 添加控件」，按目标选择添加到主页面或侧边栏。
3. 在模板库中选择控件类型。
4. 在图层列表或画布中选中新控件。
5. 在右侧属性面板完成实体、文字、样式、位置和动作设置。
6. 点击顶部「保存」，切换到「仪表盘」模式验证。

侧边栏适合跨页面使用的时间、日期、天气、折线图、底图框和导航；图片、设备按钮、空调、扫地机地图和摄像头通常放在主页面。侧边栏控件属于仪表盘共享内容，修改或删除会影响所有页面；页面独有控件请切换到主页面，或使用「复制到其他区域」。

控件类型与适用场景

控件	主要用途	是否通常需要实体
图片	背景、户型图、设备图和装饰素材	否
户型图自动导图	将已绘制户型生成到主页面，包含图片和效果控件	生成图片不需要；控制设备需绑定对应实体
3D 交互	在实时 3D 户型中切换楼层、聚焦并控制设备	展示户型无需实体；设备状态与控制需要绑定
标题按钮	标题、副标题、图标和入口	否，可选
图标按钮	带图标、文字和动作的快捷入口	否，可选
图标按钮（效果）	按实体状态切换按钮和效果图片	是，效果层可选
设备按钮	显示实体状态并执行常用控制	是
传感器	显示人体、门窗、温度等状态	是
空调 / 浴霸	温度、模式、风速及相关控制	是
扫地机器人实时地图	地图、运行状态和详情入口	是 vacuum.
摄像头实时预览	显示 Home Assistant 摄像头画面	是 camera.
时间、日期、天气	显示当前时间、日期、天气和环境信息	天气需要 weather. 实体；时间和日期不需要
折线图	显示数值实体的历史趋势	是数值实体
底图框	给一组控件提供背景、边框和柔光区域	否
导航按钮	跳转到其他页面	否

绑定 Home Assistant 实体

1. 在属性面板找到「关联实体」选择器。
2. 输入设备名称、友好名称或 entity_id 搜索并选择实体。
3. 按控件类型设置关联功能、显示字段或动作。
4. 保存后在「仪表盘」模式检查状态和控制。

常见实体域包括：灯光 light.、开关 switch.、传感器 sensor. / binary_sensor.、温控 climate.、窗帘 cover.、摄像头 camera.、扫地机 vacuum.。实体找不到时先检查连接 Home Assistant是否成功同步，不要手工猜测实体 ID。

未绑定或暂时不可用时

• 图片、标题按钮、导航按钮和底图框可以不绑定实体，仍能正常显示；
• 设备按钮、传感器、空调、摄像头、扫地机地图和折线图没有实体时不能验证真实状态或控制；
• 实体在 HA 中被删除或改名后，控件原配置不会自动变成另一台设备，应重新选择实体；
• 只换设备时保留控件并替换实体即可。

各类控件的关键设置

图片控件

图片控件用于背景、户型图、灯组开灯图、设备图片或装饰素材。图片可从「我的图片」或「栖光素材」中选择，3D 户型图导出文件位于「我的图片」的对应文件夹。

户型图、底图和灯光效果属于显示层，不会直接控制设备；需要在对应位置另加设备按钮或其他控件，绑定实体并配置动作。完整流程见导出后制作仪表盘。

常用设置包括：

• 图片布局：「自由」保留原图比例，适合设备图和装饰图；「铺满」填充整个控件区域，适合作为背景；
• 透明度：调整图片与底层内容的叠加效果；
• 位置、尺寸、缩放和旋转：用于对齐画布中的背景、户型图或设备图；
• 动作：图片默认只负责显示，如需点击后跳转页面或打开弹窗，再单独配置动作。

户型图自动导图

从「＋ 添加控件」选择「户型图自动导图」，载入已绘制的 3D 户型，设置文件夹名、位置、尺寸和视角后生成。完成后会得到普通图片与效果按钮，再分别检查实体和动作。

本轮待发布更新还支持在「3D视角 → 导图楼层」独立选择全楼或指定楼层。完整步骤、同名覆盖及重新生成注意事项见户型图自动导图。

标题按钮

标题按钮适合制作页面标题、区域标题或带装饰的入口。可设置主标题、副标题、图标、颜色、边框、圆角和光效，也可以为点按、双击和长按配置动作。它偏向信息展示和页面入口，通常不需要绑定实体。

图标按钮

图标按钮适合制作轻量的设备快捷按钮。可以绑定实体，也可以作为不绑定实体的导航或操作入口。常用设置包括 MDI 图标、标题、状态文字、开启 / 关闭颜色、大小、位置以及点按、双击和长按动作。

图标按钮不绑定实体时仍可跳转页面或打开弹窗；绑定实体后，状态显示和设备控制取决于关联实体及动作配置。

设备按钮

设备按钮用于显示设备状态并执行常用控制，适合灯光、开关、窗帘和其他需要状态反馈的实体。除了按钮本体，还可以分别设置文字、图标、状态填充和动态效果。设备按钮应绑定正确实体，并在「仪表盘」模式确认显示状态与控制结果。

图标按钮（效果）

图标按钮（效果）由控制按钮层和效果图片层组成：

• 控制按钮层：负责实体、文字、图标和点按动作；
• 效果图片层：负责按状态显示图片、透明度、淡入淡出、缩放、旋转和动画；
• 对齐本页图片：可将效果层同步到普通图片控件的布局和变换。

效果层只改变视觉呈现，不会替代控件本身的点击动作或实体控制。

导航按钮

导航按钮用于在侧边栏或页面之间跳转。目标应选择主页面，而不是 Home Assistant 实体。可设置主标题、副标题、图标、边框、光效以及选中和未选中状态的透明度。

传感器

传感器控件用于显示人体、门窗、温度等状态或数值。绑定实体后，根据返回的状态和单位显示内容；显示异常时先检查 Home Assistant 中实体是否在线、状态是否正常以及单位是否正确。

空调 / 浴霸

空调 / 浴霸控件用于温度、模式、风速和气流控制。绑定实体后可选择自动识别、空调或浴霸模式，并设置图标、标题、状态文字和气流效果；气流效果支持静态或动态显示。

如果设备同时存在 climate. 和 fan. 实体或特征，应按实际设备类型选择模式，并在预览中确认温度、模式和风速控制是否对应正确。

空调功能按 Home Assistant 实体提供的能力显示，不按格力、日立等品牌固定配置。运行模式、风速、预设和摆风等可选项以实际实体为准；HA 未提供的功能不会凭空增加。

本轮待发布更新：横向按钮与下拉

v0.4.5 之后的本轮更新，会按每组显示文字、图标和布局需要分别判断宽度：放得下一行就保留横向按钮，放不下才把该组改为下拉。摆风选项多不会把运行模式或预设模式一起改为下拉，也不以固定选项数量决定。

已知空调和浴霸模式优先显示中文，未知模式保留 HA 集成提供的名称。此规则也用于组合弹窗中的相应空调功能组；本文编写时仍需等待包含这些改动的版本发布。

例如运行模式和预设能横排、摆风有多项长名称时，仅摆风使用下拉是正常情况。遇到缺失功能，先检查 HA 中该实体是否提供对应选项，并在问题反馈中说明实际显示。

窗帘

窗帘控件支持普通窗帘或梦幻帘、双开 / 向左 / 向右方向和电机正反向设置。修改开合方向后，必须在「仪表盘」模式实际操作一次，确认画面方向与实体动作一致。

摄像头实时预览

摄像头实时预览用于显示 Home Assistant 摄像头实体的实时画面。必须绑定 camera. 实体，可设置画面是否显示、图片填充方式、边框、圆角、透明度、位置和尺寸。

编辑器预览不会获取实时画面，需保存后在「仪表盘」模式或中控页面检查；点击动作可用于打开当前摄像头的详细信息。

扫地机器人实时地图

扫地机器人实时地图用于显示扫地机器人提供的地图。绑定 vacuum. 实体后，可调整地图透明度、位置、缩放和旋转。地图控件主要负责展示，设备控制应通过设备按钮或弹窗组合完成。

时间和日期

时间控件显示当前时间，可选择 12 小时或 24 小时制、是否显示秒，并设置文字颜色、字号、粗细、字间距和位置。日期控件显示当前日期，可按需要显示星期和农历，并设置日期文字样式。两者都不需要绑定 Home Assistant 实体。

天气

天气控件需要绑定 weather. 实体，可分别显示或隐藏天气图标、温度、天气状态和湿度，并设置文字大小、颜色、字间距和行间距。显示异常时先检查天气实体是否有有效状态和属性。

折线图

折线图用于展示温度、湿度、功率等数值实体的历史变化趋势。绑定实体后，可设置刷新间隔、历史范围、是否显示当前数值、曲线圆角、精度和阈值颜色。

底图框

底图框用于制作页面或区域的装饰性背景。可设置中英文标题、边框、圆角、柔光、透明度、位置和尺寸，为一组控件提供统一的视觉区域；底图框本身不绑定实体。

动作：点按、双击和长按

可交互控件可分别配置点按、双击和长按：

• 无动作：只显示，不响应该手势；
• 切换：对当前实体执行开关或相应的切换服务，需要先绑定实体；
• 打开弹窗：打开当前实体的详情、其他实体的详情，或指定的弹窗组合；
• 跳转页面：切换到指定主页面。

选择「打开弹窗」后，再指定当前实体、其他实体或弹窗组合。完成后在「仪表盘」模式按同样手势验证。

设备弹窗功能

设备按钮、图标按钮、空调等绑定实体后，可在「设备弹窗功能」中自动适配同一 HA 设备的关联实体，也可手动指定；部分设备最多选 12 项。适合集中显示亮度、模式、位置和档位。

列表为空时，先检查 HA 设备是否同步，或保留自动适配并在预览中确认。