Fan 组件

Fan 组件用于在 ESPHome 中创建控制风扇的实体。它们用于开关风扇、控制风扇速度、风扇摆风状态等。

基础风扇配置

# 示例配置条目
fan:
  - platform: ...
    name: "Living Room Fan"

配置变量

id (可选, ID): 手动指定用于代码生成或自动化引用此风扇的 ID。
name (可选, string): 风扇的名称。
icon (可选, icon): 风扇的图标。
- 可以通过设置如 mdi:fan 的图标来自定义风扇的图标。
- 注意：命名风格必须匹配，例如 mdi:account 有效，但 mdi:Account 无效。
internal (可选, boolean): 将此组件标记为内部组件。内部组件不会暴露在前端（如 Home Assistant）。如果设备上同时安装了 Home Assistant 客户端组件，则他们仍可订阅内部组件。
- 默认情况下，如果设备的配置来源是外部源，如 YAML，则 internal 默认为 true。
restore_mode (可选, enum): 定义风扇在启动（以及首次启动）时如何恢复状态。
- NO_RESTORE：不恢复任何状态。
- RESTORE_DEFAULT_OFF：如果之前的状态在启动时未知则默认关闭。
- RESTORE_DEFAULT_ON：如果之前的状态在启动时未知则默认开启。
- RESTORE_INVERTED_DEFAULT_OFF：如果之前的状态在启动时已知则恢复反转状态，否则默认关闭。
- RESTORE_INVERTED_DEFAULT_ON：如果之前的状态在启动时已知则恢复反转状态，否则默认开启。
- 默认为 RESTORE_DEFAULT_OFF。
disabled_by_default (可选, boolean): 如果为 true，则该实体在客户端首次连接时不会显示在列表中（例如 Home Assistant）。
entity_category (可选, string): 用于 Home Assistant 实体类别的配置。如果 entity_category 设置为 ""，则设置为 None。
- 允许值："diagnostic"、"config" 或 ""。
device_class (可选, string): 风扇的设备类别。参见 https://www.home-assistant.io/integrations/fan/#device-class 以获取允许值的列表。

风扇动作

所有 fan 动作都可以通过额外的选项进行配置。

oscating (可选, boolean): 设置振荡状态。请参阅下面的 fan.oscillating 动作。
direction (可选, string): 设置方向。请参阅下面的 fan.direction 动作。
preset_mode (可选, string): 设置预设模式。请参阅 fan.preset_mode 动作。

`fan.turn_on` 动作

此动作打开风扇。

on_...:
  then:
    - fan.turn_on:
        id: my_fan

配置变量：

speed (可选, string 或 int): 设置风扇的速度（1 到 speed_count，通常为 3）。另请参见下面的 speed_level 选项。
speed_level (可选, int): 将风扇速度设置为原始级别（0 到 speed_count）。这使您可以设置超出标准速度范围的中间速度。例如，speed_count: 100 允许您设置 1-100 的级别。

`fan.turn_off` 动作

此动作关闭风扇。

on_...:
  then:
    - fan.turn_off: my_fan

`fan.toggle` 动作

此动作切换风扇的开/关状态。

on_...:
  then:
    - fan.toggle: my_fan

`fan.oscillating` 动作

此动作设置风扇的振荡状态。需要风扇支持振荡功能。

on_...:
  then:
    - fan.oscillating:
        id: my_fan
        oscillating: true

`fan.direction` 动作

此动作设置风扇的方向。需要风扇支持方向功能。

on_...:
  then:
    - fan.direction:
        id: my_fan
        direction: FORWARD

`fan.preset_mode` 动作

此动作设置风扇的预设模式。需要风扇支持预设模式功能。

on_...:
  then:
    - fan.preset_mode:
        id: my_fan
        preset_mode: "Auto"

`fan.cycle_speed` 动作

此动作循环风扇的速度设置。

on_...:
  then:
    - fan.cycle_speed: my_fan

风扇条件

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

此条件检查风扇是否为开启（或关闭）状态。

# 在条件中
on_...:
  if:
    condition:
      fan.is_on: my_fan

风扇触发器

`on_state` 触发器

此触发器在风扇状态更新时激活。它会自动被其他状态更新触发器触发，如 on_speed_set、on_direction_set 或 on_oscating_set。

fan:
  - platform: speed
    # ...
    on_state:
      - logger.log: "State changed!"

`on_speed_set` 触发器

此触发器在风扇速度设置更新时激活。

fan:
  - platform: speed
    # ...
    on_speed_set:
      - logger.log: "Speed was set!"

`on_direction_set` 触发器

此触发器在风扇方向设置更新时激活。

fan:
  - platform: speed
    # ...
    on_direction_set:
      - logger.log: "Direction was set!"

`on_oscillating_set` 触发器

此触发器在风扇振荡设置更新时激活。

fan:
  - platform: speed
    # ...
    on_oscillating_set:
      - logger.log: "Oscillating was set!"

`on_preset_set` 触发器

此触发器在风扇预设模式设置更新时激活。

fan:
  - platform: speed
    # ...
    on_preset_set:
      - logger.log: "Preset mode was set!"

`on_turn_on` 触发器

此触发器在风扇打开时激活。

fan:
  - platform: speed
    # ...
    on_turn_on:
      - logger.log: "Fan turned on!"

`on_turn_off` 触发器

此触发器在风扇关闭时激活。

fan:
  - platform: speed
    # ...
    on_turn_off:
      - logger.log: "Fan turned off!"

风扇调用

当您调用如 fan.turn_on 的动作时，ESPHome 会创建一个”调用”，并将调用分发给所有注册的处理器。这些处理器可以处理完整的调用或单个数据字段（速度、振荡等）。

您可以定义自己的处理器或”拦截”调用来创建自定义行为：

`fan.register` lambda

此 lambda 在任何风扇属性发生更改时调用。可以使用它来拦截风扇调用并实现自定义行为。

fan:
  - platform: template
    id: my_fan
    # ...
    fan.register:
      then:
        - lambda: |-
            ESP_LOGD("main", "Fan call state=%s", call.get_state() ? "ON" : "OFF");
            if (call.get_speed().has_value()) {
              ESP_LOGD("main", "  Speed: %d", *call.get_speed());
            }
            // 返回 'true' 以表示调用已被处理
            return true;

lambda 函数参数如下：

call (type FanCall): 调用对象，包含调用中提供的所有值（state、speed、oscillating、direction 等）。

lambda 应返回 bool：

如果处理器处理了调用则返回 true
如果处理器未处理调用则返回 false（将调用传递给下一个处理器）

Fan 组件

基础风扇配置

配置变量

风扇动作

fan.turn_on 动作

fan.turn_off 动作

fan.toggle 动作

fan.oscillating 动作

fan.direction 动作

fan.preset_mode 动作

fan.cycle_speed 动作

风扇条件

fan.is_on / fan.is_off 条件

风扇触发器

on_state 触发器

on_speed_set 触发器

on_direction_set 触发器

on_oscillating_set 触发器

on_preset_set 触发器

on_turn_on 触发器

on_turn_off 触发器