Fan 组件

使用 fan 领域，你可以创建在 Home Assistant 前端中显示为风扇的组件。风扇可以开关，可选地具有 1 到风扇最大支持速度之间的速度，还可以具有摆风和方向输出。

基础 Fan 配置

fan:
  - platform: ...
    name: ...

配置变量：

id (可选, string)：手动指定用于代码生成的 ID。至少必须指定 id 和 name 之一。
name (可选, string)：风扇的名称。至少必须指定 id 和 name 之一。

NOTE

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

icon (可选, icon)：手动设置在前端为风扇使用的图标。
restore_mode (可选)：控制风扇在启动时如何尝试恢复状态。
- NO_RESTORE - 不恢复任何状态。
- RESTORE_DEFAULT_OFF - 尝试恢复状态，如果无法恢复则默认为 OFF。
- RESTORE_DEFAULT_ON - 尝试恢复状态，如果无法恢复则默认为 ON。
- RESTORE_INVERTED_DEFAULT_OFF - 尝试恢复与之前状态相反的状态，如果无法恢复则默认为 OFF。
- RESTORE_INVERTED_DEFAULT_ON - 尝试恢复与之前状态相反的状态，如果无法恢复则默认为 ON。
- ALWAYS_OFF（默认）- 启动时始终将风扇初始化为 OFF。
- ALWAYS_ON - 启动时始终将风扇初始化为 ON。
internal (可选, boolean)：将此组件标记为内部组件。内部组件不会暴露给前端（如 Home Assistant）。仅指定 id 而不指定 name 将隐式地将其设置为 true。
disabled_by_default (可选, boolean)：如果为 true，则此实体不应添加到任何客户端的前端（通常是 Home Assistant）中，除非用户通过手动启用它（通过 Home Assistant UI）。默认为 false。
entity_category (可选, string)：实体的类别。参见 https://developers.home-assistant.io/docs/core/entity/#generic-properties 查看可用选项列表。设置为 "" 以移除默认的实体类别。
如果启用了 Webserver 且选择了版本 3，则包含 Webserver 组件的所有其他选项。参见 Webserver 版本 3。

MQTT 选项：

direction_state_topic (可选, string)：用于发布风扇方向状态更改的主题（选项：forward、reverse）。
direction_command_topic (可选, string)：用于接收风扇方向命令的主题（选项：forward、reverse、toggle）。
oscillation_state_topic (可选, string)：用于发布风扇摆风状态更改的主题。
oscillation_command_topic (可选, string)：用于接收摆风命令的主题。
speed_level_state_topic (可选, int)：用于发布数字风扇速度状态更改的主题（范围：0 到速度数量）。
speed_level_command_topic (可选, int)：用于接收数字速度命令的主题（范围：0 到速度数量）。
speed_state_topic (可选, string)：用于发布风扇速度状态更改的主题（选项：LOW、MEDIUM、HIGH）。
speed_command_topic (可选, string)：用于接收速度命令的主题（选项：LOW、MEDIUM、HIGH）。
包含 MQTT 组件的所有其他选项。

自动化触发器：

on_state (可选, Action)：在风扇状态改变时执行的自动化。参见 fan.on_state 触发器。
on_turn_on (可选, Action)：在风扇打开时执行的自动化。参见 fan.on_turn_on / fan.on_turn_off 触发器。
on_turn_off (可选, Action)：在风扇关闭时执行的自动化。参见 fan.on_turn_on / fan.on_turn_off 触发器。
on_direction_set (可选, Action)：在风扇方向改变时执行的自动化。参见 fan.on_direction_set 触发器。
on_oscillating_set (可选, Action)：在风扇摆风状态改变时执行的自动化。参见 fan.on_oscillating_set 触发器。
on_speed_set (可选, Action)：在风扇速度改变时执行的自动化。参见 fan.on_speed_set 触发器。
on_preset_set (可选, Action)：在风扇预设模式改变时执行的自动化。参见 fan.on_preset_set 触发器。

`fan.toggle` 操作

执行时切换给定 ID 的风扇的 ON/OFF 状态。

on_...:
  then:
    - fan.toggle: fan_1

`fan.turn_off` 操作

执行时关闭给定 ID 的风扇。

on_...:
  then:
    - fan.turn_off: fan_1

`fan.turn_on` 操作

执行时打开给定 ID 的风扇。

on_...:
  then:
    - fan.turn_on:
        id: fan_1
    # 简写：
    - fan.turn_on: fan_1

配置选项：

id (必填, ID)：风扇的 ID。
oscillating (可选, boolean, templatable)：设置风扇的摆风状态。默认不更改摆风状态。
speed (可选, int, templatable)：设置风扇的速度级别。可以是 1 到风扇最大速度级别之间的数字。
direction (可选, string, templatable)：设置风扇的方向。可以是 forward 或 reverse。默认不更改方向。

`fan.cycle_speed` 操作

执行时递增给定 ID 的风扇的速度级别。如果风扇的速度级别已设置在最大值，则执行后风扇将循环关闭，除非 off_speed_cycle 设置为 false。

on_...:
  then:
    - fan.cycle_speed:
        id: fan_1
        off_speed_cycle: true
    # 简写：
    - fan.cycle_speed: fan_1

配置选项：

id (必填, ID)：风扇的 ID。
off_speed_cycle (可选, boolean, templatable)：确定风扇在循环通过最高速度后是否循环关闭。可以是 true 或 false。如果为 false，风扇将循环到最低速度而不是关闭。默认为 true。

`fan.is_on` / `fan.is_off` 条件

此条件在给定的风扇处于打开或关闭状态时通过。

# 在触发器中：
on_...:
  if:
    condition:
      fan.is_on: my_fan
      # is_off 同理
    then:
    - script.execute: my_script

`fan.on_state` 触发器

此触发器在风扇状态改变时激活。它将在通过 API（例如在 Home Assistant 中）或本地通过自动化或 lambda 函数设置状态时触发。 Fan 的指针以名为 x 的变量形式可用。

fan:
  - platform: speed # 或其他平台
    # ...
    on_state:
    - logger.log:
        format: "Fan State changed!  Fan Speed is %d!"
        args: [ x->speed ]

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

此触发器在风扇打开或关闭时激活。如果打开或关闭风扇的命令与当前状态已经匹配，则不会触发。

fan:
  - platform: speed # 或其他平台
    # ...
    on_turn_on:
    - logger.log: "Fan Turned On!"
    on_turn_off:
    - logger.log: "Fan Turned Off!"

`fan.on_direction_set` 触发器

此触发器在风扇方向改变时激活。它将在通过 API（例如在 Home Assistant 中）或本地通过自动化或 lambda 函数设置方向时触发。新方向以名为 x（类型 FanDirection）的变量形式可用。

fan:
  - platform: speed # 或其他平台
    # ...
    on_direction_set:
    - logger.log:
        format: "Fan Direction was changed to %s!"
        args: [ 'x == FanDirection::FORWARD ? "FORWARD" : "REVERSE"' ]

`fan.on_oscillating_set` 触发器

此触发器在风扇摆风状态改变时激活。它将在通过 API（例如在 Home Assistant 中）或本地通过自动化或 lambda 函数设置状态时触发。新摆风状态以名为 x 的变量形式可用。

fan:
  - platform: speed # 或其他平台
    # ...
    on_oscillating_set:
    - logger.log:
        format: "Fan Oscillating State was changed to %s!"
        args: [ ONOFF(x) ]

`fan.on_speed_set` 触发器

此触发器在风扇速度改变时激活。它将在通过 API（例如在 Home Assistant 中）或本地通过自动化或 lambda 函数设置速度时触发。新速度以名为 x 的变量形式可用。

fan:
  - platform: speed # 或其他平台
    # ...
    on_speed_set:
    - logger.log:
        format: "Fan Speed was changed to %d!"
        args: [ x ]

`fan.on_preset_set` 触发器

此触发器在风扇预设模式改变时激活。它将在通过 API（例如在 Home Assistant 中）或本地通过自动化或 lambda 函数设置预设模式时触发。新模式以名为 x 的变量形式可用。

fan:
  - platform: speed # 或其他平台
    # ...
    on_preset_set:
      - logger.log:
          format: "Fan preset mode was changed to %s!"
          args: [ x.c_str() ]

Lambda 调用

在 lambda 中，你可以调用风扇的多个方法来执行一些高级操作（更多信息参见完整的 API 参考）。

state：获取风扇的当前状态（开/关）。

    // 在 lambda 内，获取风扇状态并条件性执行某项操作
    if (id(my_fan).state) {
      // 风扇已开启，在此执行某项操作
    } else {
      // 风扇已关闭，在此执行其他操作
    }

speed：获取风扇的当前速度。

    // 在 lambda 内，获取风扇速度并条件性执行某项操作
    if (id(my_fan).speed == 2) {
      // 风扇速度为 2，在此执行某项操作
    } else {
      // 风扇速度不是 2，在此执行其他操作
    }

oscillating：获取风扇的当前摆风状态。

    // 在 lambda 内，获取风扇摆风状态并条件性执行某项操作
    if (id(my_fan).oscillating) {
      // 风扇正在摆风，在此执行某项操作
    } else {
      // 风扇没有摆风，在此执行其他操作
    }

direction：获取风扇的当前方向。

    // 在 lambda 内，获取风扇方向并条件性执行某项操作
    if (id(my_fan).direction == FanDirection::FORWARD) {
      // 风扇方向为正向，在此执行某项操作
    } else {
      // 风扇方向为反向，在此执行其他操作
    }

get_preset_mode()：获取风扇的当前预设模式。返回 StringRef。

    // 在 lambda 内，获取风扇预设模式并条件性执行某项操作。
    // 当未设置预设模式时，get_preset_mode() 返回空的 StringRef，
    // 因此在需要非空值的位置使用前请检查 has_preset_mode()。
    if (id(my_fan).has_preset_mode() && id(my_fan).get_preset_mode() == "auto") {
      // 风扇预设模式为 "auto"，在此执行某项操作。
    } else {
      // 风扇预设模式未设置，或不是 "auto"。在此执行其他操作。
    }

turn_off() / turn_on() / toggle()：从代码中手动打开/关闭风扇。类似于 fan.turn_on、fan.turn_off 和 fan.toggle 操作，但可用于复杂的 lambda 表达式。

    // 关闭风扇
    auto call = id(my_fan).turn_off();
    call.perform();

    // 打开风扇并设置速度、摆风和方向
    auto call = id(my_fan).turn_on();
    call.set_speed(2);
    call.set_oscillating(true);
    call.set_direction(FanDirection::REVERSE);
    call.perform();

    // 切换风扇的开/关
    auto call = id(my_fan).toggle();
    call.perform();

set_preset_mode() / has_preset_mode()：设置或检查风扇的预设模式。

    // 在 lambda 内，获取风扇预设模式并条件性执行某项操作。
    // 当未设置预设模式时，get_preset_mode() 返回空的 StringRef，
    // 因此在需要非空值的位置使用前请检查 has_preset_mode()。
    if (id(my_fan).has_preset_mode() && id(my_fan).get_preset_mode() == "auto") {
      // 风扇预设模式为 "auto"，在此执行某项操作。
    } else {
      // 风扇预设模式未设置，或不是 "auto"。在此执行其他操作。
    }

    // 打开风扇并设置预设模式
    auto call = id(my_fan).turn_on();
    call.set_preset_mode("auto");
    call.perform();

Fan 组件

基础 Fan 配置

fan.toggle 操作

fan.turn_off 操作

fan.turn_on 操作

fan.cycle_speed 操作

fan.is_on / fan.is_off 条件

fan.on_state 触发器

fan.on_turn_on / fan.on_turn_off 触发器

fan.on_direction_set 触发器

fan.on_oscillating_set 触发器

fan.on_speed_set 触发器

fan.on_preset_set 触发器