企业官网建设流程全解析

Home Assistant remote.toggle 动作完全指南：通过远程实体一键切换设备开关状态

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

remote.toggle是 Home Assistant 中面向remote（远程遥控）域的开关切换动作，它把"开"与"关"合并成一条指令，发送给负责控制电视、投影仪、功放等影音设备的远程实体。当被控设备本身用同一条命令即可完成开与关（例如许多红外/蓝牙遥控协议采用单键切换）时，用它可以让自动化脚本更简洁。读完本文，你将掌握如何在自动化与脚本中通过 UI 或 YAML 调用remote.toggle、如何用实体/设备/区域/楼层/标签指定目标，以及两个可直接落地的完整自动化示例。

remote.toggle 动作是什么

Toggle via remote动作会通过一个 remote 域实体发送切换（toggle）命令。它适用于以下场景：

• 被控设备使用同一条命令即可在开与关之间切换（单键电源协议）；
• 你只关心"状态翻转"，不要求结果必须是确定的开或关；
• 希望用最少的动作数量完成媒体系统、投影仪、电视等设备的电源切换。

动作的行为由目标 remote 实体当前的状态决定：设备处于开状态则切换为关，处于关状态则切换为开。因此，如果自动化的业务逻辑要求可预测的开或关结果，官方建议改用 Turn on via remote 或 Turn off via remote（在目标远程实体支持的前提下）。

从 UI 创建 Toggle via remote 动作

如果更习惯使用可视化编辑器，Home Assistant 会引导你逐步完成动作配置：选择目标、微调选项并保存，全程无需接触 YAML。在自动化或脚本中添加该动作的步骤如下：

1. 进入Settings>Automations & scenes（通过{% my automations %}快捷入口）。
2. 打开现有的自动化或脚本，或选择Create新建一个。
3. 如果是新建自动化，在When部分添加触发条件；脚本则无需触发器——它由其他对象调用时才会运行。
4. 在Then do部分选择Add action。
5. 选择要控制的对象：在By target（目标方式，见下文 动作目标）下，选择负责发送命令的远程实体、设备、区域、楼层或标签。
6. 从该目标可用的动作列表中选择Toggle via remote。
7. 选择Save保存。

UI 选项：该动作在 UI 中没有额外的选项，与remote.turn_on支持可选activity参数不同，remote.toggle只负责状态翻转，不涉及活动（activity）选择。

在 YAML 中使用 remote.toggle

对于直接编写 YAML 的用户，本动作的技术参考如下：YAML 中调用该动作的名称为remote.toggle。基础示例如下：

action: remote.toggle target: entity_id: remote.living_room

该示例通过remote.living_room实体发送切换命令。YAML 选项：remote.toggle没有额外的 YAML 选项，动作所需的全部信息就是target。

动作目标（Targets of the action）

remote.toggle必须指定目标（target）。目标是动作的作用对象，你可以把动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对目标背后所有匹配的 remote 域实体执行动作：

• Entity（实体）：单个具体的 remote 实体，例如remote.living_room；
• Device（设备）：属于某设备的所有 remote 实体；
• Area（区域）：某个房间或区域内的所有 remote 实体；
• Floor（楼层）：某一楼层上的所有 remote 实体；
• Label（标签）：共享某个标签的所有 remote 实体。

你还可以在一次动作中混合不同目标类型，例如同时添加一个具体实体和一个区域作为目标，让动作对两者一并执行。从源码结构看，这一目标解析机制由 source/_includes/actions/targets.md 统一注入到所有动作页面中，是整个动作系统共用的目标处理逻辑。

实战示例 1：用仪表盘按钮一键切换媒体系统

场景：当用户创建的 helper 按钮（此处为input_button.media_toggle）被按下时，切换客厅遥控器（remote.living_room）的开关状态。

• Trigger（触发器）：State（状态）
  • Entity：Media toggle（input_button.media_toggle）
• Action（动作）：Toggle via remote
  • Target：Living room remote（remote.living_room）

对应 YAML 完整自动化：

automation: alias: "Toggle living room remote from helper button" triggers: - trigger: state entity_id: input_button.media_toggle actions: - action: remote.toggle target: entity_id: remote.living_room

实战示例 2：有人进入区域时切换投影仪

场景：当 Paulus（person.paulus）进入影院区域（zone.cinema）时，切换投影仪遥控器（remote.projector）的开关状态。

• Trigger（触发器）：Zone（区域）
  • Entity：Paulus（person.paulus）
  • Zone：Cinema（zone.cinema）
  • Event：Enter（进入）
• Action（动作）：Toggle via remote
  • Target：Projector remote（remote.projector）

对应 YAML 完整自动化：

automation: alias: "Toggle projector remote when Paulus enters cinema zone" triggers: - trigger: zone entity_id: person.paulus zone: zone.cinema event: enter actions: - action: remote.toggle target: entity_id: remote.projector

与其他 remote 动作的配合使用

remote.toggle属于 remote 域动作家族，官方在同一文档体系中维护着它的三个相关动作：

• Turn on via remote：发送开命令；部分支持活动（activity）的远程实体还可以通过可选参数activity（YAML 中类型为 string，非必填）启动已保存的活动，例如日落时用data: { activity: "Evening TV" }启动晚间电视活动；
• Turn off via remote：发送关命令，例如在 23:00 定时关闭客厅媒体系统，或在某人离开家时关闭遥控器；
• remote.send_command：发送自定义命令（在相关文档的related_actions中列出）。

在实际集成中可以看到这些动作的组合用法。以 Logitech Harmony 集成 为例，其文档展示了remote.turn_on、remote.turn_off和remote.send_command的调用方式，其中remote.turn_on的目标同样通过entity_id: remote.bed_room_hub这类实体指定，并可通过current_activity状态属性获取当前活动。Xbox 集成 则在自动化示例中直接使用了remote.toggle动作，印证了该动作在真实集成中的可组合性。选择哪个动作取决于业务语义：需要确定性开关用turn_on/turn_off，只需翻转状态用toggle。

注意事项（Good to know）

• remote.toggle的动作目标是remote 域实体；
• 切换命令的结果取决于设备当前状态：设备处于开则切为关，处于关则切为开。如果需要可预测的开或关结果，请改用 Turn on via remote 或 Turn off via remote（在远程设备支持的前提下）；
• 如果远程设备不可用（unavailable），Home Assistant 将无法发送该命令——在编写自动化时建议结合设备状态条件（如device_off状态判断）做好前置检查。

小结

remote.toggle是 remote 域中最精简的开关动作：零附加选项、目标机制完善、UI 与 YAML 双通道可用，非常适合"一键翻转"类影音控制场景。将其与remote.turn_on（支持活动启动）、remote.turn_off（确定性关闭）按业务语义搭配使用，即可覆盖绝大多数远程遥控设备的自动化需求。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io