企业官网建设流程全解析

Home Assistant 风扇调速完全指南：深入解析 fan.set_percentage 动作

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

在 Home Assistant 中，Set fan speed（设置风扇速度）动作（fan.set_percentage）是精确控制风扇转速的核心工具：它允许你把风扇移动到某个具体的速度档位——比如 25% 提供安静气流，或者 100% 快速降温。本篇指南以 fan.set_percentage 官方动作文档 为主体，结合 Fan 集成文档 及动作侧的相关资料（如 fan.increase_speed、fan.decrease_speed、fan.set_preset_mode）进行纵深解读。读完本文，你将掌握：该动作的适用前提、UI 与 YAML 两种使用方式、target（目标）体系的完整用法、参数说明，以及可直接复制到自动化中的完整实战示例。

一、这个动作解决什么问题？

根据官方文档的定位，"Set fan speedaction is useful when you know the exact speed you want"——当你知道确切想要的转速时，这个动作是最直接的方案。它与相对调速动作形成互补：

在 Fan 集成文档 中，"Setting the speed as a percentage" 被列为 Fan 实体提供的基础功能之一，同列的功能还包括开关、预设模式、摆动、旋转方向以及步进调速。需要特别强调的是：并非每台风扇都支持全部动作——一个风扇具体可用哪些动作，取决于该设备对外暴露的特性（feature）。

二、在 UI 中使用该动作

如果你习惯可视化搭建自动化，Home Assistant 会引导你逐步完成整个动作配置，无需任何 YAML 知识。官方文档给出的完整步骤为：

1. 进入Settings>Automations & scenes。
2. 打开一个现有的自动化或脚本；或者选择Create automation>Create new automation。
3. 如果是新建自动化，先在When（触发条件）部分添加一个触发器。
4. 在Then do（执行动作）部分，选择Add action。
5. 选择要控制的对象：在By target（见下文 Targets 一节）下，选取你想要控制的风扇；也可以选择某个区域（area）、楼层（floor）、设备（device）或标签（label）。
6. 从该目标可用的动作列表中，选择Set fan speed。
7. 在Percentage字段中，设置你想要的转速。
8. 点击Save保存。

UI 中的选项

三、在 YAML 中使用该动作

YAML 技术参考

如果你直接编写 YAML，或者想知道 Home Assistant 底层到底做了什么，本节给出完整的技术参考，包括字段名、类型与必填要求。

在 YAML 中，该动作的引用名为fan.set_percentage。一个最基础的示例：

action: fan.set_percentage target: entity_id: fan.office data: percentage: 40

这段配置把fan.office设置为 40% 转速。

YAML 选项（Options in YAML）

四、Targets：动作的目标体系

该动作需要一个目标（target）。目标就是动作的作用对象。你可以把动作指向单个实体（entity）、设备、区域、楼层或标签，Home Assistant 会对目标背后所有匹配的fan实体执行该动作。官方文档列出的目标类型如下：

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

你还可以在一次动作中混用不同类型的目标。例如，同一个动作中同时添加一个具体实体和一个区域，让动作同时作用于这两者。

五、Good to know：使用须知

官方文档明确列出以下几点，务必牢记：

• 该动作仅对支持转速控制的风扇可用。不支持速度调节的设备不会暴露此动作。
• 0被选择器允许，但部分设备可能把 0 视为关闭，或直接忽略它。因此实际表现取决于具体设备固件/驱动的实现。
• 如果只想按步向上或向下调整速度，应改用 Increase fan speed 或 Decrease fan speed 动作——这两个动作的增量字段（percentage_step）是可选的，留空时由集成自行决定步长。

六、动手试试：在 Actions 工具中直接调用

准备实际测试？打开Settings>Tools>Actions（开发者工具中的 Actions 服务页面），搜索该动作，填入字段后点击Perform action。你可以在不写一行 YAML 的情况下，在真实实体上看到动作的执行结果。

七、完整实战示例

以下示例来自官方文档的 "More examples" 部分，均可以直接复制并适配你自己的环境。

示例一：早上把办公室风扇调到安静转速

用一个不那么干扰通话的轻气流开始一天：

• 触发器：时间 08:00
• 动作：Set fan speed
• 目标：办公室风扇
• 百分比：35

automation: alias: "Office fan to 35 percent" triggers: - trigger: time at: "08:00:00" actions: - action: fan.set_percentage target: entity_id: fan.office data: percentage: 35

示例二：午后阳光照进来时把客厅风扇调到全速

当下午的太阳开始加热房间时，把风扇推到全速以快速降温：

• 触发器：时间 15:00
• 动作：Set fan speed
• 目标：客厅风扇
• 百分比：100

automation: alias: "Living room fan to full speed" triggers: - trigger: time at: "15:00:00" actions: - action: fan.set_percentage target: entity_id: fan.living_room data: percentage: 100

示例三：与步进调速配合的"三步走"自动化

如果你希望在同一台设备上组合"精确设定 + 相对微调"，可以同时参考相邻动作的用法：

# 中午 12:00 相对升速 10%（参照 fan.increase_speed 的示例） automation: - alias: "Increase office fan at midday" triggers: - trigger: time at: "12:00:00" actions: - action: fan.increase_speed target: entity_id: fan.office data: percentage_step: 10 # 晚间 23:00 相对降速 10%（参照 fan.decrease_speed 的示例） - alias: "Decrease bedroom fan speed at night" triggers: - trigger: time at: "23:00:00" actions: - action: fan.decrease_speed target: entity_id: fan.bedroom data: percentage_step: 10

示例四：与命名预设模式互补

如果你的风扇提供 low / medium / high 等命名模式（例如 ESPHome 的 Speed Fan 组件默认提供 Low、Medium、High 预设），可以用fan.set_preset_mode切换模式，而非直接设置原始百分比。当设备既支持百分比又支持预设时，两个动作可以按场景各取所长：

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"

八、从源码结构看：它在 Fan 域中的位置

从 source/_actions 目录的归类可以看出，fan.set_percentage与另外七个动作同属于 Fan 域（domain: fan），构成完整的风扇控制能力集：

• fan.turn_on/fan.turn_off/fan.toggle：开关与切换
• fan.set_percentage：精确设定百分比转速（本文主题）
• fan.increase_speed/fan.decrease_speed：步进调速
• fan.set_preset_mode：切换命名预设模式
• fan.oscillate：控制摆动
• fan.set_direction：改变旋转方向

在 Fan 集成文档 中，该集成明确列出风扇实体的通用能力清单（开关、百分比调速、预设模式、摆动、旋转方向、步进调速），并再次强调："Not every fan supports every action. The actions available for a specific fan depend on the features exposed by that device."（并非每台风扇都支持所有动作，可用动作取决于设备暴露的特性）。这也解释了为什么fan.set_percentage只在支持速度控制的风扇上出现——底层驱动必须实现了对应的速度特性，该动作才会被注册到实体上。

九、相关动作

以下动作与fan.set_percentage配合使用效果最佳：

• Increase fan speed：不需要选择精确的最终速度，即可获得更多气流；按步或按指定的百分比增量上调转速。
• Decrease fan speed：不需要选择精确的最终速度，即可获得更柔和的气流；按步或按指定的百分比增量下调转速。

十、仍然卡住了？

Home Assistant 社区能快速提供帮助：可以加入 Discord 进行实时交流，在社区论坛发帖时附上你调用的动作以及预期行为，或在 /r/homeassistant 子版块分享你的问题。用自然语言向 AI 助手描述你的需求，它们也能解释动作或推荐合适的动作。

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