Switch 组件

switch 域包含所有应显示为开关且只能被打开（ON）或关闭（OFF）的平台。

基础开关配置

switch:
  - platform: ...
    name: "Switch Name"
    icon: "mdi:restart"

配置变量：

id（可选，字符串）：手动指定用于代码生成的 ID。id 和 name 中至少需要指定一个。
name（可选，字符串）：开关的名称。id 和 name 中至少需要指定一个。

NOTE

如果您为设备设置了 friendly_name，并且希望开关使用该名称，可以设置 name: None。

icon（可选，图标）：手动设置前端界面中传感器使用的图标。
inverted（可选，布尔值）：是否反转二进制状态，即将 ON 状态报告为 OFF，反之亦然。默认为 false。
internal（可选，布尔值）：将此组件标记为内部组件。内部组件不会暴露给前端界面（如 Home Assistant）。仅指定 id 而不指定 name 会隐式设置此选项为 true。
restore_mode（可选）：控制开关在启动时如何尝试恢复状态。注意：并非所有组件都支持 restore_mode。请查看特定组件的文档以了解此功能在特定组件或设备上的工作方式。关于 ESP8266 上的状态恢复，另请参阅 esp8266 部分中的 restore_from_flash。
- RESTORE_DEFAULT_OFF - 尝试恢复状态，如果无法恢复则默认为 OFF。
- RESTORE_DEFAULT_ON - 尝试恢复状态，如果无法恢复则默认为 ON。
- RESTORE_INVERTED_DEFAULT_OFF - 尝试恢复与之前状态相反的状态，如果无法恢复则默认为 OFF。
- RESTORE_INVERTED_DEFAULT_ON - 尝试恢复与之前状态相反的状态，如果无法恢复则默认为 ON。
- ALWAYS_OFF（默认）- 启动时始终将开关初始化为 OFF。
- ALWAYS_ON - 启动时始终将开关初始化为 ON。
- DISABLED - 不执行任何操作，由下游平台组件决定。例如，组件可以读取硬件并确定状态，或有特定的配置选项来调节初始状态。
除非特定平台定义了其他默认值，否则默认值为 ALWAYS_OFF。
on_turn_on（可选，Action）：当开关被打开时执行的自动化。参见 switch.on_turn_on / switch.on_turn_off 触发器。
on_turn_off（可选，Action）：当开关被关闭时执行的自动化。参见 switch.on_turn_on / switch.on_turn_off 触发器。
disabled_by_default（可选，布尔值）：如果为 true，则此实体不应添加到任何客户端的前端界面（通常是 Home Assistant），除非用户手动启用（通过 Home Assistant UI）。默认为 false。
entity_category（可选，字符串）：实体的类别。请参阅 https://developers.home-assistant.io/docs/core/entity/#generic-properties 获取可用选项列表。设置为 "" 可移除默认实体类别。
device_class（可选，字符串）：开关的设备类别。请参阅 https://www.home-assistant.io/integrations/switch/#device-class 获取可用选项列表。
如果启用了 MQTT，则支持 MQTT 组件的所有其他选项。
如果启用了 Webserver 并选择了版本 3，则支持 Webserver 组件的所有其他选项。请参阅 Webserver 版本 3。

`switch.toggle` 动作

此动作执行时切换具有给定 ID 的开关状态。

on_...:
  then:
    - switch.toggle: relay_1

`switch.turn_on` 动作

此动作执行时打开具有给定 ID 的开关。

on_...:
  then:
    - switch.turn_on: relay_1

`switch.turn_off` 动作

此动作执行时关闭具有给定 ID 的开关。

on_...:
  then:
    - switch.turn_off: relay_1

`switch.control` 动作

此动作允许您比基本的 turn_on 和 turn_off 动作更灵活地控制开关。它接受一个可模板化的 state 参数，当期望的开关状态是动态确定时非常有用。

on_...:
  then:
    - switch.control:
        id: relay_1
        state: true

    # 或使用模板
    - switch.control:
        id: relay_1
        state: !lambda |-
          return id(some_sensor).state > 50.0;

配置变量：

id（必填，ID）：要控制的开关的 ID。
state（必填，布尔值，可模板化）：要设置的开关状态。true 打开开关，false 关闭开关。

`switch.is_on` / `switch.is_off` 条件

此条件检查给定开关是否为 ON（或 OFF）。

# 在某个触发器中：
on_...:
  if:
    condition:
      # is_off 语法相同
      switch.is_on: my_switch

lambda 调用

从 lambda 中，您可以在所有开关上调用多个方法来执行一些高级操作（更多信息请参阅完整的 API 参考）。

publish_state()：手动使开关发布新状态并在内部存储它。如果与上次内部状态不同，它还会发布到前端界面。

    // 在 lambda 中，使开关报告特定状态
    id(my_switch).publish_state(false);
    id(my_switch).publish_state(true);

NOTE

请记住，这不会改变开关的实际状态。它只会改变前端界面和内部的状态。如果您想改变开关的实际状态，需要调用 turn_on()、 turn_off() 或 toggle()。

例如，如果您使用的是 Gpio，调用 publish_state() 不会改变 GPIO 引脚电平。要做到这一点，您需要调用 turn_on()、 turn_off()、toggle() 或 control()。这同样适用于其他开关平台。

state：获取开关的当前状态。

    // 在 lambda 中，获取开关状态并根据条件执行操作
    if (id(my_switch).state) {
      // 开关为 ON，在这里执行操作
    } else {
      // 开关为 OFF，在这里执行其他操作
    }

turn_off() / turn_on()：从代码中手动将开关打开/关闭。类似于 switch.turn_on 和 switch.turn_off 动作，但可以在复杂的 lambda 表达式中使用。

    id(my_switch).turn_off();
    id(my_switch).turn_on();
    // 切换开关
    id(my_switch).toggle();

control()：使用布尔参数控制开关状态。这提供了一个统一的接口来动态设置开关状态。

    // 在 lambda 中，根据条件控制开关
    id(my_switch).control(true);   // 打开
    id(my_switch).control(false);  // 关闭
    id(my_switch).control(some_condition);  // 根据条件设置

`switch.on_turn_on` / `switch.on_turn_off` 触发器

此触发器在每次开关被打开时激活。它在开关组件确认状态后立即激活（例如，在它自己切换为 ON/OFF 之后）。

switch:
  - platform: gpio  # 或任何其他平台
    # ...
    on_turn_on:
    - logger.log: "Switch Turned On!"
    on_turn_off:
    - logger.log: "Switch Turned Off!"

`switch.on_state` 触发器

此触发器在每次开关状态改变时激活（无论是 ON 还是 OFF）。它以布尔变量 x 的形式提供新状态，可在自动化中使用。

switch:
  - platform: gpio  # 或任何其他平台
    # ...
    on_state:
      - light.control:
          id: my_light
          state: !lambda return x;
      - if:
          condition:
            lambda: 'return x;'
          then:
            - logger.log: "Switch is now ON!"
          else:
            - logger.log: "Switch is now OFF!"

变量 x 是一个表示新状态的布尔值：

true 当开关打开时
false 当开关关闭时

另请参阅

API Reference: switch.h

Switch 组件

基础开关配置

switch.toggle 动作

switch.turn_on 动作

switch.turn_off 动作

switch.control 动作

switch.is_on / switch.is_off 条件