企业官网建设流程全解析

Home Assistant switch.turn_on 动作完全指南：从 UI 到 YAML 开启开关实体

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

本文围绕 Home Assistant 官方文档中的switch.turn_on动作（Turn on switch）展开，覆盖开关实体（switch entity）的概念、该动作在自动化界面中的完整配置步骤、YAML 写法、目标（target）机制、与switch.turn_off/switch.toggle的取舍，并给出可直接复制的咖啡机定时开机示例。读完本文，你可以在不写一行 YAML 的情况下通过 UI 配置"开灯/通电"类自动化，也能精确理解 YAML 中action: switch.turn_on的行为边界与幂等特性。

一、动作定位：switch.turn_on 做什么

switch.turn_on用于将一个开关实体（switch entity）打开。文档中对该动作的官方描述为 "Turns a switch on."，定义见 source/_actions/switch.turn_on.markdown。

一个开关实体代表具有简单开/关状态的对象，例如：

• 智能插座（smart plug）
• 墙壁电源插座（wall outlet）
• 继电器（relay）
• 设备上一个可以启用/禁用的功能

两条关键行为约束：

1. 状态只有两态：switch 实体只有 On 和 Off 两种状态。如果想控制亮度或颜色，应当改用 light 实体和light.turn_on动作。
2. 幂等（idempotent）：如果开关已经是打开状态，再次执行此动作不会发生任何变化。这意味着在自动化中重复触发它是安全的，不需要先用条件判断当前状态。

从仓库中的 Switch 集成文档可以看到更完整的状态模型：除了On与Off之外，实体还可能处于Unavailable（当前不可用）或Unknown（状态尚未可知）状态。该文档同时确认了 switch 集成注册了三个控制动作：switch.turn_on、switch.turn_off和switch.toggle，这三者共同构成开关控制的核心动作集。

此外，switch 实体支持以下设备类别（device class）：

• None：通用开关，默认值，无需设置；
• outlet：电源插座类开关；
• switch：通用开关。

设备类别只影响实体在界面上的展示方式，不影响switch.turn_on的执行逻辑。

二、在用户界面中使用 switch.turn_on

如果你偏好可视化构建，Home Assistant 的自动化界面会一步步引导你完成配置，无需任何 YAML 知识。完整步骤如下：

1. 进入Settings>Automations & scenes（自动化与场景）。
2. 打开一个已有的自动化或脚本，或者选择Create automation>Create new automation。
3. 如果是新建自动化，需要在When部分添加触发器；脚本则不需要触发器，它由其他调用者执行。
4. 在Then do部分，选择Add action。
5. 选择要控制的对象。在By target下选择要打开的开关；也可以选择一个区域、楼层、设备或标签。
6. 在针对该目标列出的动作中选择Turn on switch。
7. 选择Save。

UI 中的可配置项

这个动作没有目标之外的任何附加选项。也就是说，界面里你能填的只有"目标"，其余字段由系统自动处理。

三、在 YAML 中使用 switch.turn_on

在 YAML 中，该动作写作switch.turn_on。一个最小示例如下：

action: | action: switch.turn_on target: entity_id: switch.coffee_machine

这会打开switch.coffee_machine实体。

YAML 中的可配置项

与 UI 一致，该动作没有 target 之外的任何 YAML 选项。字段结构固定为：

动作的目标（Targets）

该动作要求提供 target。target 是动作的操作对象，你可以将动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对该目标背后的每个 switch 实体执行该动作：

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

还允许在同一个动作中混合不同的目标类型。例如，可以在同一个动作里同时加入一个具体实体和一个区域，动作会对两者同时生效。

关于target的更多语法细节（例如设备/区域/楼层的完整写法），可参考仓库中的 自动化动作文档。

四、完整实战示例：早上自动开启咖啡机

文档给出的示例场景：早上打开为咖啡机供电的智能插座，让你起床时咖啡机已经就绪。

• 触发器：时间 06:45
• 动作：Turn on switch（打开开关）
  • 目标：Coffee machine（咖啡机）

对应 YAML：

automation: | - alias: "Start the coffee machine in the morning" triggers: - trigger: time at: "06:45:00" actions: - action: switch.turn_on target: entity_id: switch.coffee_machine

要点解析：

• triggers使用time触发器，at: "06:45:00"表示每天 06:45:00 执行；
• actions中的switch.turn_on目标指向插座实体switch.coffee_machine；
• 由于该动作幂等，即使咖啡机当晚没有断电，06:45 的执行也只会"什么都不做"，不会造成任何副作用。

仓库中也有真实蓝图使用了这个动作的组合思路：例如 EasyEnergy 低价开关蓝图 会在电价低峰时段自动操作开关类实体，体现了"触发器 + switch 动作"这一自动化范式在实际仓库中的落地形态。

手动测试：开发者工具

想立即验证动作效果，可以打开Settings>Tools>Actions（开发者工具 / 动作面板），搜索switch.turn_on，填入目标字段后点击Perform action。这样可以在不写任何 YAML 的情况下，对真实实体执行一次动作并观察结果。

五、需要注意的行为细节

来自文档 "Good to know" 部分的补充说明：

• 只有开和关两态：想控制亮度或颜色时，不要滥用 switch，应使用 light 实体和light.turn_on动作。
• 设备功能以开关形式暴露：有些设备会把自身设置项暴露为 switch 实体。打开这样的开关，意味着在设备上启用对应功能；关闭则禁用（对应switch.turn_off）。

六、与相关动作的取舍

switch.turn_on有三个天然搭配的动作，文档在 front matter 中通过related_actions显式声明了它们：

选择建议：

• 需要确定的最终状态（比如"确保插座通电"）时用switch.turn_on/switch.turn_off；
• 需要无脑翻转时用switch.toggle——批量目标下每个实体会被独立翻转，原来是开的会关，原来是关的会开。

此外，switch 实体还有配套的状态触发器（如water_heater.turned_on类似的switch.turned_on语义由触发器体系提供）与条件判断（如 switch.is_off），可以在同一套自动化里组合出"检测到断开后自动恢复供电"这类逻辑。

七、小结

• switch.turn_on是 Home Assistant 中最基础的动作之一，字段极简：action+target，无任何附加选项；
• 幂等语义使它可以安全地放入定时、事件等高频触发的自动化中；
• target 支持实体、设备、区域、楼层、标签五种粒度且可混用，是批量控制的关键；
• 两态限制是它的边界：涉及亮度/颜色的场景请转向light.turn_on。

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