Home Assistant 中设置 Modern Forms 风扇睡眠定时器：action 详解与自动化实战
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
导读
modern_forms.set_fan_sleep_timer是 Home Assistant 官方 Modern Forms 集成提供的一个 action（动作/服务），用于给 Modern Forms 智能 Wi-Fi 风扇设置独立的睡眠定时器：定时器到期后风扇自动关闭。本文以该 action 的官方文档为主体，结合仓库中的集成文档与动作模板源码，完整讲解在 UI 与 YAML 两种方式下如何使用该 action、全部参数细节、目标（target）选择机制，并给出"睡前让卧室风扇运行一小时"的完整自动化示例，最后补充 NTP 依赖这一关键使用前提。
一、动作概述：它做什么
modern_forms.set_fan_sleep_timer用于在 Modern Forms 风扇上设置一个睡眠定时器。当定时器到期时，风扇会自动关闭。
这一动作有两个显著特点：
- 与灯光定时器相互独立：Modern Forms 风扇和灯拥有各自独立的睡眠定时器，可分别设置、分别清除。本动作只作用于风扇；
- 配套的清除动作：如果定时器已设置但想取消，应使用配套的 modern_forms.clear_fan_sleep_timer 动作——清除定时器不会关闭风扇，只是取消尚未到期的定时任务。
关联动作：文档 frontmatter 中声明了
related_actions，即 modern_forms.clear_fan_sleep_timer 与 modern_forms.set_light_sleep_timer，它们共同构成了 Modern Forms 睡眠定时器动作家族。
从集成文档可知，Modern Forms 集成（ha_domain: modern_forms）自 2021.7 版本加入 Home Assistant，采用Local Polling的 IoT 类别，支持通过Zeroconf自动发现，提供fan、light、binary_sensor、number、sensor、switch等多种平台实体。
二、从 UI 设置风扇睡眠定时器
如果你更习惯可视化构建自动化或脚本，Home Assistant 的 UI 会逐步引导你完成配置（仓库中的 ui_header.md 对此流程做了统一说明：选择目标、微调选项、保存，无需编写 YAML）。操作步骤如下：
- 进入Settings>Automations & scenes（设置 > 自动化与场景）；
- 打开一个已有的自动化或脚本，或选择Create automation>Create new automation（新建自动化 > 创建新自动化）；
- 如果是新建自动化，在When（何时）部分添加一个触发器。脚本则不需要触发器——脚本在别的对象调用它们时才运行；
- 在Then do（然后执行）部分，选择Add action（添加动作）；
- 选择你要控制的对象。在By target（按目标，见下文"动作的目标"一节）下选择你的 Modern Forms 风扇；
- 从该目标展示出的动作列表中，选择Modern Forms: Set fan sleep timer（Modern Forms：设置风扇睡眠定时器）；
- 输入Sleep time（睡眠时间），单位为分钟；
- 选择Save（保存）。
UI 中的选项
| 选项 | 说明 |
|---|---|
| Sleep time（睡眠时间） | 定时器设置的分钟数，取值范围1 到 1440（即最多一天）。必填。 |
该动作在 UI 中仅此一个选项，sleep_time为必填项。
三、在 YAML 中使用该动作
3.1 基础 YAML 示例
在 YAML 中，该动作以modern_forms.set_fan_sleep_timer引用。一个基础示例如下：
action: modern_forms.set_fan_sleep_timer target: entity_id: fan.bedroom data: sleep_time: 60上面这段配置的含义是：为卧室风扇设置一个 60 分钟的睡眠定时器，一小时后风扇自动关闭。
3.2 YAML 参数参考
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
sleep_time | integer | 是 | 定时器设置的分钟数，取值范围1 到 1440（一天）。 |
3.3 动作的目标（Targets）
该动作必须指定目标（target）。目标就是动作作用的对象，可以将动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对目标背后所有匹配的fan实体执行该动作（对应模板源码 targets.md）：
- Entity（实体）：某个具体的
fan实体，例如fan.living_room； - Device（设备）：属于某台设备的所有
fan实体； - Area（区域）：某个房间或区域内的所有
fan实体； - Floor（楼层）：某个楼层上的所有
fan实体； - Label（标签）：共享某个标签的所有
fan实体。
你还可以在同一个动作中混合不同类型的目标，例如同时添加一个具体实体和一个区域，让该动作同时作用于它们。
3.4 在开发者工具中试运行
无需写任何 YAML，你也可以直接测试该动作：打开Settings>Tools>Actions（设置 > 工具 > 动作），搜索modern_forms.set_fan_sleep_timer，填写字段后选择Perform action（执行动作），即可在真实实体上立即看到效果（见 try_it.md）。
四、实战自动化：睡前让卧室风扇运行一小时
官方文档给出了一个完整的自动化场景：每天睡前设置一小时的睡眠定时器，让风扇在你入睡期间运转，之后自动关闭。
- 触发器（Trigger）：定时时间
- 动作（Action）：Modern Forms：设置风扇睡眠定时器
完整 YAML 如下：
automation: alias: "Bedroom fan sleep timer" triggers: - trigger: time at: "22:30:00" actions: - action: modern_forms.set_fan_sleep_timer target: entity_id: fan.bedroom data: sleep_time: 60该自动化每天晚上 22:30 触发，为fan.bedroom设置 60 分钟睡眠定时器，风扇在 23:30 自动关闭，正好覆盖入睡阶段。
五、与配套动作协同：清除与灯光定时器
5.1 清除风扇睡眠定时器
modern_forms.clear_fan_sleep_timer 用于清除风扇上的睡眠定时器。清除定时器不会关闭风扇，它只是取消尚未到期的定时任务。其 YAML 用法同样需要 target，且没有额外参数：
action: modern_forms.clear_fan_sleep_timer target: entity_id: fan.bedroom5.2 灯光睡眠定时器
Modern Forms 的灯光也有独立的睡眠定时器（modern_forms.set_light_sleep_timer/modern_forms.clear_light_sleep_timer），可独立于风扇定时器设置与清除。注意集成文档的提示：如果风扇没有安装灯单元，Light 实体与相关动作不会出现。
六、关键前提：NTP 依赖与网络限制
使用睡眠定时器前，必须了解一个关键的硬件行为（详见集成文档末尾的 note）：
Modern Forms 风扇通过 NTP（
pool.ntp.org）设置内部时钟，并据此检查睡眠定时器是否到期。睡眠定时器只有在风扇能访问互联网上的 NTP 服务器时才有效。你可以阻断风扇的云访问、仅放行出站 NTP（UDP 123 端口），睡眠定时器依然能正常工作。
这一约束决定了实际部署策略：如果你希望本地化控制、限制风扇的云端连接，务必保留 UDP 123 端口的出站 NTP 流量，否则睡眠定时器将无法按时到期触发关风扇。
此外，结合集成文档可知，集成还会提供以下与定时器状态相关的实体，可用于自动化联动：
- Binary sensors：
fan sleep timer active status（风扇睡眠定时器激活状态）、light sleep timer active status（灯光睡眠定时器激活状态）； - Sensors：
fan sleep timer time expiring（风扇睡眠定时器剩余时间）、light sleep timer time expiring（灯光睡眠定时器剩余时间）。
例如，你可以用"风扇睡眠定时器激活状态"作为条件，避免重复设置定时器，或用"剩余时间"传感器在定时器快到期前触发提醒。
七、故障排查与社区支持
- 检查实体是否存在：若你的风扇没有安装灯单元，灯光相关动作不会出现在目标动作列表中；
- 检查网络：确认风扇能访问 NTP 服务器（UDP 123 端口出站），这是定时器正常工作的前提；
- 检查目标：确认
target.entity_id指向真实的fan实体 ID； - 检查取值范围：
sleep_time必须在 1–1440 之间，超出范围会被拒绝。
如果仍然无法工作，Home Assistant 社区提供了多个求助渠道（见 stuck.md）：可以加入 Discord 实时交流、在社区论坛发帖（附上你调用的动作与预期结果），或在 subreddit 上分享问题；也可以让 AI 助手用自然语言描述需求，让它为你解释动作或推荐正确的动作。
八、小结
modern_forms.set_fan_sleep_timer是一个参数极简（仅一个必填的sleep_time）但实用性很高的动作：
- UI 路径：Automations & scenes → Add action → Modern Forms: Set fan sleep timer；
- YAML 路径：
action: modern_forms.set_fan_sleep_timer+target+data.sleep_time（1–1440 分钟）； - 配套动作：clear_fan_sleep_timer（清除定时器）、set_light_sleep_timer（灯光定时器）；
- 关键前提：风扇需能访问 NTP 服务器（UDP 123），定时器才能正常到期生效。
配合集成自带的定时器状态 binary sensor 与剩余时间 sensor，你可以构建出"睡前自动运行、到点自动关闭、状态可视化"的完整智能风扇体验。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
、Broker Load 与 Pipe 三种方案对比与实战)