企业官网建设流程全解析

Home Assistant climate.set_fan_mode 动作完全指南：在自动化与脚本中设置温控设备风机模式

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

导读

climate.set_fan_mode是 Home Assistant 中用于设置 Climate（HVAC/温控）设备风扇模式的核心动作（action），典型的应用场景包括：通过自动化在室温升高时自动把空调风速调到高档、按时间段切换风扇静音/自动模式，或在脚本中批量调整多台温控设备的风扇档位。读完本文，你将掌握该动作在 UI 与 YAML 两种方式下的完整用法、target五种定位方式、fan_mode参数的取值规则，以及如何结合源码级的实体属性与真实集成（如 Palazzetti、IntesisHome、MQTT Climate）理解其底层工作原理。

动作概述：它做了什么

依据仓库中的动作定义文档 source/_actions/climate.set_fan_mode.markdown，该动作的作用是：

"Sets the fan mode of a climate device."

即设置 Climate 设备的风扇模式。它面向的对象是 HVAC 实体（恒温器、空调、热泵、暖气炉等），例如把空调的风扇从低速切到高速，或切换为自动/静音模式。它属于 Home Assistant 官方提供的core action，action 名为climate.set_fan_mode，所属域（domain）为climate。

值得强调的是：风扇模式与 HVAC 模式（climate.set_hvac_mode，如heat/cool/off）和摆动模式（climate.set_swing_mode、climate.set_swing_horizontal_mode）是三个相互独立的控制维度。文档的related_actions字段即列出了这三个相关动作，说明它们经常配合使用。

从用户界面（UI）调用该动作

如果你习惯使用可视化编辑器构建自动化和脚本，可按以下步骤操作（对应文档 source/_actions/climate.set_fan_mode.markdown 的逐步指引）：

1. 进入设置（Settings）> 自动化与场景（Automations & scenes）。
2. 打开一个已有的自动化或脚本；也可以选择创建自动化（Create automation）> 创建新自动化（Create new automation）。
3. 如果是新建自动化，需要在当……时（When）区域添加一个触发器。脚本（Script）不需要触发器——它们在被其他逻辑调用时才运行。
4. 在然后执行（Then do）区域，选择添加动作（Add action）。
5. 选择你要控制的对象：在目标（By target）下选中要控制的 Climate 设备（关于 target 的详细说明见下文「动作的目标（Targets）」一节）。
6. 在该目标展示出的动作列表中，选择设置恒温器风扇模式（Set thermostat fan mode）。
7. 设置要应用的风扇模式（Fan mode）。
8. 点击保存（Save）。

UI 中的选项

在 YAML 中使用该动作

文档明确指出：在 YAML 中，该动作以climate.set_fan_mode引用。一个最基本的示例如下：

action: climate.set_fan_mode target: entity_id: climate.living_room data: fan_mode: low

这段配置把climate.living_room的风扇设置为低档（low）。

YAML 选项参考

在自动化中使用：炎热午后自动调高风速

文档附带了一个完整的实战示例——当室内温度超过阈值时自动把空调风速调高：

• 触发器（Trigger）：室内温度升至 26 °C 以上
• 动作（Action）：设置恒温器风扇模式
  • 目标（Target）：客厅恒温器
  • 风扇模式（Fan mode）：high

对应的完整 YAML：

- alias: "Increase the fan speed on a hot afternoon" triggers: - trigger: numeric_state entity_id: sensor.living_room_temperature above: 26 actions: - action: climate.set_fan_mode target: entity_id: climate.living_room data: fan_mode: high

这个例子体现了典型的「温度传感器数值状态触发器 + Climate 动作」组合：numeric_state触发器监听sensor.living_room_temperature超过 26°C，随后动作把客厅温控设备的风扇切到高档。你可以在自动化或脚本中直接复制并替换实体 ID 与阈值使用。

动作的目标（Targets）

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

• 实体（Entity）：某一个具体的 climate 实体，例如climate.living_room。
• 设备（Device）：该设备下的每一个 climate 实体。
• 区域（Area）：某个房间/区域内的每一个 climate 实体。
• 楼层（Floor）：某一楼层上的每一个 climate 实体。
• 标签（Label）：共享某个标签的每一个 climate 实体。

此外，你可以在同一次动作中混合选择不同类型的目标。例如，可以在同一个动作里同时加入一个具体实体和一个区域，让动作一次性对两者执行。这意味着一次climate.set_fan_mode调用就能批量同步多台温控设备的风扇模式，而无需逐个编写动作。

好习惯与注意事项

可用风扇模式取决于设备

文档的 "Good to know" 部分明确强调了一条核心原则：可用的风扇模式取决于 Climate 设备本身。不同厂商、不同型号的温控设备支持的档位集合完全不同，写入不受支持的模式通常会被设备忽略或导致动作失败。因此在编写自动化前，建议先在设置 > 设备与服务中查看目标设备实体的fan_modes属性，确认其支持的模式列表。

先实测再写 YAML

文档附带的 "Try it yourself" 提示建议：无需写任何 YAML，即可通过设置 > 工具（Tools）> 动作（Actions）打开开发者工具，搜索该动作、填写字段并点击执行动作（Perform action），在真实实体上观察效果（来源：source/_includes/actions/try_it.md）。这是验证模式取值是否被设备接受、排查目标选择是否正确的最快方式。

组合使用相关动作

文档的related_actions字段将climate.set_swing_mode、climate.set_swing_horizontal_mode和climate.set_hvac_mode列为配套动作。在真实场景中，一次完整的舒适度调节往往需要同时设置 HVAC 模式（制热/制冷）、风扇模式和摆动模式，例如制冷模式下配合高档风速和水平摆动。

源码级原理：从实体属性到设备命令

climate 实体的fan_mode属性

根据 source/_integrations/climate.markdown，Climate 实体具有一个名为fan_mode的属性，用于表示风扇当前的状态：

注意这里区分两个概念：属性fan_mode是实体的当前状态（风扇开/关或当前档位），而动作climate.set_fan_mode是对设备下发指令（把风扇设置为某个模式）。结合 source/_docs/scripts/conditions.markdown 中的条件用法，你可以把该属性用于状态条件判断，例如：

conditions: - condition: state entity_id: climate.living_room_thermostat attribute: fan_mode state: "auto"

即「只有当风扇模式属性为auto时才继续执行后续动作」。同一份文档还展示了针对fan_modes（支持的档位列表属性）的列表匹配写法，可用于校验设备能力。

真实集成的模式取值示例

各集成对fan_mode取值的支持各不相同，仓库中的集成文档给出了可参考的真实取值：

• Palazzetti（source/_integrations/palazzetti.markdown）：支持set_fan_mode，取值为0到5递增的风扇速度、High（最高档）以及Auto（让炉子自动设定最佳风速）。
• IntesisHome（source/_integrations/intesishome.markdown）：在其支持的 action 列表中明确包含climate.set_fan_mode，配合climate.set_temperature、climate.set_operation_mode、climate.set_swing_mode等一起使用。
• MQTT Climate（source/_integrations/climate.mqtt.markdown）：提供了fan_modes配置项，用于声明支持的档位列表，默认值为['auto', 'low', 'medium', 'high']；同时通过fan_mode_state_topic订阅风扇模式状态、fan_mode_command_topic下发风扇模式命令。完整配置示例中可以看到fan_modes: ["high", "medium", "low"]与fan_mode_command_topic: "study/ac/fan/set"的搭配。

这些示例印证了文档的核心论断：fan_mode的合法取值完全由设备/集成决定，从数字档位（0–5）到语义档位（low/medium/high/auto）再到特殊值（High、on/off）都可能出现，使用时务必先确认目标设备的fan_modes属性。

常见问题排查

如果调用该动作后设备没有响应，可以按以下顺序排查（参考文档结尾的 "Still stuck?" 提示思路）：

1. 确认设备支持的模式：检查实体属性中的fan_modes列表，确保data.fan_mode的值在其中。
2. 在开发者工具中实测：用「设置 > 工具 > 动作」手动执行一次，排除 YAML 语法或目标选择问题。
3. 确认目标类型：若使用设备/区域/标签作为目标，确认目标背后确实关联了 climate 实体（例如某些设备可能没有提供 climate 实体，此时动作会提示无匹配目标）。
4. 查看日志：Home Assistant 日志中通常会有动作执行失败的报错信息，指出具体原因。

总结

climate.set_fan_mode是控制温控设备风扇的核心动作：UI 路径为「自动化与场景 → 添加动作 → 设置恒温器风扇模式」，YAML 路径为action: climate.set_fan_mode+target+data.fan_mode。其目标支持实体/设备/区域/楼层/标签五种方式并可混合使用，fan_mode的合法取值严格取决于设备能力（如 Palazzetti 的0–5/High/Auto，MQTT Climate 默认的auto/low/medium/high）。配合 climate 集成文档 中的fan_mode属性与状态条件，你可以构建出"按温度自动提速"这类实用的舒适度自动化。

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