Home Assistant humidifier.turn_on 动作详解：用 UI、YAML 与自动化开启加湿器

Home Assistant humidifier.turn_on 动作详解：用 UI、YAML 与自动化开启加湿器

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

humidifier.turn_on是 Home Assistant 用于开启加湿类设备的核心动作，可在自动化、脚本中调用，一键启动加湿器、除湿机或湿度控制器的运行。本文基于官方文档仓库中该动作的完整参考页，覆盖其界面操作步骤、YAML 语法、目标（target）类型、开发者工具验证方式与典型自动化场景，并结合文档站的实际渲染机制补充实现层面的佐证，读完即可在自己的 Home Assistant 环境中直接落地使用。

动作概览

根据 动作定义文件 的 front matter，该动作的关键元信息如下：

官方说明的用途是：使用该动作开启加湿器（humidifier）、除湿机（dehumidifier）或湿度控制器（hygrostat），例如让房间开始增加湿度。需要注意的一点是：这个动作仅对 humidifier 实体生效（Good to know 一节明确指出 “This action only works with humidifier entities”）。

在用户界面中添加该动作

如果你习惯可视化构建自动化和脚本，Home Assistant 会逐步引导你完成配置，选择目标、保存即可，无需编写 YAML。官方文档给出的完整操作步骤为：

1. 进入Settings > Automations & scenes（设置 > 自动化与场景）；
2. 打开一个已有的自动化或脚本，或选择Create automation>Create new automation；
3. 如果是新建自动化，在When（触发条件）部分添加一个触发器；脚本不需要触发器，脚本由其他对象调用时执行；
4. 在Then do（执行动作）部分，选择Add action；
5. 选择要控制的对象：在By target之下（参见下文“目标类型”）选中要开启的加湿器；
6. 在该目标列出的可用动作中，选择Turn on humidifier；
7. 选择Save保存。

UI 中的选项：该动作除目标（target）之外没有额外选项——也就是说，选对设备后直接保存即可生效，无需设置任何参数。

YAML 语法与基础示例

在 YAML 中，该动作以humidifier.turn_on作为引用名。官方文档给出的基础示例如下：

action: humidifier.turn_on target: entity_id: humidifier.bedroom

这条动作的作用就是开启实体humidifier.bedroom。

YAML 选项：与 UI 一致，该动作除target之外没有额外的 YAML 选项。从仓库的站点生成逻辑可以印证这一点：doc_collections_data.rb 在构建动作索引 JSON 时，只会从页面中的{% options_yaml %}块提取参数字段（p字段）；humidifier.turn_on页面不含该块，因此它在动作索引中没有参数字段映射——“无额外选项”在文档站的数据层面得到了一致的体现。

相比之下，同域的动作humidifier.set_humidity就有必填参数：见 set_humidity 文档，其data中的humidity为必填整数（0–100 的百分比）。这说明“turn 类”动作在设计上是零参数的开关型动作，参数化的控制（如目标湿度）由同域其他动作承担。

目标（Targets of the action）类型

该动作必须提供目标，目标是动作的作用对象。该说明由所有动作页共享的模板 targets.md 渲染，针对 humidifier 域的具体含义如下：

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

Home Assistant 会对目标背后匹配的每一个 humidifier 实体执行该动作。此外，可以在同一个动作里组合多种目标类型：例如同时添加一个具体实体和一个区域作为目标，动作会同时作用于两者。这一点对批量管理多台加湿器（如“开启所有卧室设备的加湿功能”）非常实用。

用开发者工具直接验证

在把动作写入自动化之前，官方文档建议先在开发者工具中实测：打开Settings > Tools > Actions（开发者工具 > 动作），搜索humidifier.turn_on，填写字段后选择Perform action。这样无需写任何 YAML 就能看到动作在你真实实体上的效果。该入口由共享模板 try_it.md 提供，是所有动作页统一的验证路径。

实战示例：每天早上自动开启卧室加湿器

官方文档提供了一个完整的自动化示例：在固定时间开启加湿器，比如在你醒来前开始为房间加湿。

• 触发条件（Trigger）：Time: 07:00（时间 07:00）
• 动作（Action）：Turn on humidifier
  • 目标（Target）：卧室加湿器

对应的完整 YAML 如下（triggers/actions为新版自动化 YAML 的键名写法）：

- alias: "Turn on the bedroom humidifier in the morning" triggers: - trigger: time at: "07:00:00" actions: - action: humidifier.turn_on target: entity_id: humidifier.bedroom

按此结构，把at: "07:00:00"换成你的目标时间、entity_id换成实际的加湿器实体（或用area_id、device_id等目标类型）即可直接复用。

配套动作：关闭、切换与设置目标湿度

humidifier.turn_on的 front matter 中声明了四个关联动作，它们共同构成加湿器域的完整控制面。以下均来自本仓库中对应的动作文档：

1.humidifier.turn_off（关闭加湿器）

来源：turn_off 文档。同样无额外选项，典型用法是夜间关闭以降噪：

- alias: "Turn off the bedroom humidifier at night" triggers: - trigger: time at: "23:00:00" actions: - action: humidifier.turn_off target: entity_id: humidifier.bedroom

2.humidifier.toggle（切换加湿器开/关）

来源：toggle 文档。开启时关闭、关闭时开启，适合绑定物理按钮，其官方示例使用input_button的状态触发：

- alias: "Toggle the bedroom humidifier with a button" triggers: - trigger: state entity_id: input_button.humidifier_toggle actions: - action: humidifier.toggle target: entity_id: humidifier.bedroom

3.humidifier.set_humidity（设置目标湿度）

来源：set_humidity 文档。这是同域中唯一带参数的动作，humidity为必填整数（0–100 百分比），官方示例：

- alias: "Raise the bedroom humidity in the morning" triggers: - trigger: time at: "07:15:00" actions: - action: humidifier.set_humidity target: entity_id: humidifier.bedroom data: humidity: 60

值得注意的是该文档 “Good to know” 中的限制说明：不同设备支持的湿度范围可能比 0–100 更窄，超出设备支持范围的动作会失败。这提示在组合使用turn_on与set_humidity时，应以设备实际能力为准。

注意事项与常见误区

• 仅对 humidifier 实体生效：对非 humidifier 域实体（如普通的 switch）调用该动作不会达到预期，这是官方文档明确列出的限制；
• 无参数可配：不要试图在turn_on的data中传入湿度、模式等参数，参数化控制应交给humidifier.set_humidity、humidifier.set_mode等专门动作；
• 目标可以批量：通过 area/floor/label 目标可一次开启多台设备，避免逐台编写entity_id；
• 先用开发者工具验证：在自动化正式启用前，通过Settings > Tools > Actions实测一次，确认目标实体响应正常。

文档站实现侧写：这个页面是如何生成的

对关注文档站本身的读者，本页的仓库结构值得了解：

• 动作正文位于 source/_actions/humidifier.turn_on.markdown，属于 Jekyll 站点配置的actions集合，front matter 中的action、domain字段是索引键；
• 页面通过 Liquid include 复用共享段落：ui_header.md（UI 使用导语）、yaml_header.md（YAML 使用导语）、targets.md（目标类型说明）、try_it.md（开发者工具验证）、more_examples.md（更多示例引导）与 related.md（根据 front matter 的related_actions自动渲染关联动作链接列表）；
• doc_collections_data.rb 插件会在构建时把所有动作页扫描为actions_json，以<domain>.<name>（即humidifier.turn_on）为键，携带描述（d）、页面 URL（u）、标题（t）和参数映射（p），供前端 prism-doc-links.js 之类的能力在代码块中做动作链接提示；由于turn_on页面没有{% options_yaml %}块，其索引条目不包含参数映射，与“该动作无 YAML 选项”的事实一致；
• 全部动作的可搜索总目录由 source/actions/index.html 提供，按 domain 分组渲染（humidifier 域即包含本文介绍的turn_on及其关联动作）。

综上，humidifier.turn_on是一个“零参数、强目标”的开关型动作：掌握target的多种指向方式（实体/设备/区域/楼层/标签）、开发者工具的验证流程，以及与turn_off/toggle/set_humidity的分工，就足以构建覆盖加湿器日常场景的完整自动化方案。

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