企业官网建设流程全解析

Home Assistant fan.set_preset_mode 动作完全指南：风扇预设模式的 UI 与 YAML 配置实战

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

fan.set_preset_mode是 Home Assistant 中用于将风扇实体切换到命名预设模式（如 low、medium、high、sleep、auto）的官方动作（Action）。本指南以 source/_actions/fan.set_preset_mode.markdown 为骨架，结合 fan 集成 与 MQTT 风扇集成 的源码级配置说明，完整讲解该动作的适用场景、UI 与 YAML 两种配置方式、目标（Target）选取规则，并给出可直接复制的自动化示例。读完本文，你将能够在自动化与脚本中准确调用该动作，并理解预设模式在实体背后的真实来源与限制。

什么时候应该使用 fan.set_preset_mode

当你的风扇提供命名模式（例如 low、medium、high、sleep、auto）时，fan.set_preset_mode就是切换这些内置模式的正确动作。它与 fan.set_percentage（直接设置原始速度百分比）形成互补：

• 有命名模式可用：优先用fan.set_preset_mode，语义清晰、可读性好；
• 只有速度范围没有命名模式：改用fan.set_percentage设置 0–100 的百分比速度；
• 打开/关闭风扇：使用fan.turn_on/fan.turn_off。

从 fan 集成 的说明可以看出，设置预设模式（Setting a preset mode）是 Home Assistant 风扇平台对外提供的一项标准能力，但能否使用完全取决于提供该风扇实体的集成是否实现并暴露了预设模式。

预设模式从哪来：由集成决定的能力边界

一个关键事实是：可用的预设模式并非 Home Assistant 内置的固定列表，而是由提供风扇实体的集成定义的。不同设备、不同集成，预设模式名称各不相同。

以文档中提到的 ESPHome Speed Fan 为例，其默认提供Low、Medium、High三档预设。而以 MQTT 风扇为例，fan.mqtt 集成配置文档 明确要求你通过preset_modes配置项声明风扇支持的模式列表：

preset_modes: - "auto" - "smart" - "whoosh" - "eco" - "breeze"

该配置项的官方说明为："List of preset modes this fan is capable of running at"，常见示例包括auto、smart、whoosh、eco和breeze，默认值为空列表[]。这从实现层面印证了文档中的提示：预设模式名称因设备而异，切换到不存在的模式不会生效。

MQTT 风扇中与预设模式相关的底层配置

如果你使用 MQTT 风扇，理解下面这些配置项有助于排查fan.set_preset_mode不生效的问题（详见 fan.mqtt 集成）：

• preset_mode_command_topic：发布命令以切换预设模式的 MQTT 主题（fan.set_preset_mode动作最终会把目标模式写入该主题）；
• preset_mode_state_topic：订阅以接收预设模式状态的 MQTT 主题；
• preset_mode_value_template：从该状态主题收到的 payload 中提取preset_mode值的模板；
• preset_mode_command_template：生成发送到preset_mode_command_topic的 payload 的模板；
• payload_reset_preset_mode：当在preset_mode_state_topic收到该特殊 payload 时，将preset_mode状态属性重置为unknown，默认值为"None"。

下面的完整 MQTT 风扇配置（摘自 fan.mqtt 集成文档，包含 10 档速度范围与 5 个预设模式）展示了预设模式与百分比速度如何在一个实体上共存：

mqtt: - fan: name: "Bedroom Fan" state_topic: "bedroom_fan/on/state" command_topic: "bedroom_fan/on/set" direction_state_topic: "bedroom_fan/direction/state" direction_command_topic: "bedroom_fan/direction/set" oscillation_state_topic: "bedroom_fan/oscillation/state" oscillation_command_topic: "bedroom_fan/oscillation/set" percentage_state_topic: "bedroom_fan/speed/percentage_state" percentage_command_topic: "bedroom_fan/speed/percentage" preset_mode_state_topic: "bedroom_fan/preset/preset_mode_state" preset_mode_command_topic: "bedroom_fan/preset/preset_mode" preset_modes: - "auto" - "smart" - "whoosh" - "eco" - "breeze" qos: 0 payload_on: "true" payload_off: "false" payload_oscillation_on: "true" payload_oscillation_off: "false" speed_range_min: 1 speed_range_max: 10

在这个示例中，preset_modes中列出的每一个模式，都会成为你在 UI 或 YAML 中可以传给fan.set_preset_mode的合法取值。

在用户界面（UI）中使用

如果你更习惯用可视化方式搭建自动化与脚本，Home Assistant 会引导你一步步完成配置，全程不需要编写 YAML（见 actions/ui_header.md）。操作步骤如下：

1. 进入Settings>Automations & scenes；
2. 打开一个现有的自动化或脚本，或选择Create automation>Create new automation；
3. 如果是新建自动化，在When区域添加一个触发器；
4. 在Then do区域选择Add action；
5. 选择要控制的对象：在By target（目标方式，见下文 目标（Targets））下选择要控制的风扇，也可以选择区域、楼层、设备或标签；
6. 在针对该目标显示的动作列表中，选择Set fan preset mode；
7. 在Preset mode下选择要使用的模式；
8. 选择Save保存。

UI 中的选项

在 YAML 中使用

如果你直接编写 YAML，或者想精确了解 Home Assistant 底层执行了什么，本节给出完整的技术参考（见 actions/yaml_header.md）：列出 YAML 中使用的字段名、类型以及哪些字段是必填的。

在 YAML 中，该动作的引用名就是fan.set_preset_mode。一个基础示例如下：

action: fan.set_preset_mode target: entity_id: fan.bedroom data: preset_mode: "sleep"

这段配置将fan.bedroom切换到sleep预设模式。

YAML 中的选项

目标（Targets）

fan.set_preset_mode必须指定目标。目标是动作的作用对象：你可以将动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对该目标背后的每一个匹配 fan 实体执行此动作（见 actions/targets.md）：

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

你还可以在同一个动作中组合不同类型的多个目标。例如，同时添加一个具体实体和一个区域作为目标，动作会对这两者一起执行。

实战自动化示例

以下示例覆盖了文档中给出的两个真实场景，可直接复制到你的automations.yaml或通过 UI 导入。

自动化：夜间将卧室风扇设为低档

如果卧室风扇使用 ESPHome Speed Fan 预设，可以在就寝时间自动切换到Low，获得更安静的气流。

• 触发器（Trigger）：时间 22:30
• 动作（Action）：Set fan preset mode
• 目标（Target）：Bedroom fan
• 预设模式（Preset mode）：low

YAML 完整写法：

automation: alias: "Bedroom fan low preset" triggers: - trigger: time at: "22:30:00" actions: - action: fan.set_preset_mode target: entity_id: fan.bedroom data: preset_mode: "low"

自动化：回家时将客厅风扇设为高档

在温暖的天气回到家时，可以将 ESPHome Speed Fan 立即切换到High，快速获得更强的气流。

• 触发器（Trigger）：进入区域（Zone entered）
  • 目标（Target）：Alex
  • 区域（Zone）：Home
• 动作（Action）：Set fan preset mode
  • 目标（Target）：Living room fan
  • 预设模式（Preset mode）：high

YAML 完整写法：

automation: alias: "Living room fan high preset on arrival" triggers: - trigger: zone.entered target: entity_id: person.alex options: zone: zone.home actions: - action: fan.set_preset_mode target: entity_id: fan.living_room data: preset_mode: "high"

两个示例共同展示了fan.set_preset_mode在自动化中最典型的两种触发模式：时间触发与地理位置（区域进入）触发，动作本体则始终保持"目标 + 预设模式"的简洁结构。

需要了解的要点（Good to know）

• 该动作仅对支持预设模式的风扇可用。如果你的风扇实体没有预设模式能力，动作会执行失败或没有效果；
• 可用的预设模式来自风扇集成，因此模式名称因设备而异——同一个动作在不同设备上可选的预设值可能完全不同；
• 要设置百分比速度而不是命名模式，请改用 fan.set_percentage 动作。

动手测试：在开发者工具中立即尝试

想先验证效果再写进自动化？打开Settings>Tools>Actions（开发者工具中的动作界面），搜索fan.set_preset_mode，填写字段后点击Perform action。你会立即看到真实实体上的状态变化，全程无需编写一行 YAML（见 actions/try_it.md）。

相关动作

fan.set_preset_mode常与以下动作配合使用（见 actions/related.md 的机制说明及文档 front matter 中的related_actions声明）：

• fan.turn_on：打开风扇（预设模式通常需要风扇处于开启状态才生效）；
• fan.set_percentage：按 0–100 百分比设置风扇速度，用于没有命名模式的场景。

结合本文的 UI 步骤、YAML 字段参考与两个自动化示例，你现在可以针对任意支持预设模式的风扇实体，在界面或纯 YAML 环境中完成fan.set_preset_mode的配置与排错。

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