企业官网建设流程全解析

Home Assistant timer.start 动作详解：启动与重启 Timer 倒计时的完整指南（UI + YAML）

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

本篇技术指南围绕 Home Assistant 文档仓库中的 timer.start 动作参考 展开，讲解如何启动一个 Timer 实体、如何用新的时长重启它、以及如何在不指定时长时恢复暂停的倒计时。读完本文，你将掌握timer.start在可视化 UI 与 YAML 两种工作流中的完整操作路径、duration参数的格式与默认行为、动作目标（Targets）的指定规则，以及它与 Timer 实体状态机和其他四个 timer 动作的配合方式，能够直接在自己的自动化或脚本中落地一个可用的倒计时方案。

动作语义：timer.start 做什么

timer.start的作用可以从 动作元数据 中的描述确认：

Starts a timer, or restarts it with a new duration.（启动一个计时器，或用新的时长重启它）

它的核心行为可以拆成三条规则：

1. 显式指定duration：用给定时长启动（或重启）计时器。
2. 省略duration，且计时器处于暂停（paused）状态：计时器按暂停时剩余的剩余时间继续倒计时，这就是“恢复暂停计时器”的标准做法。
3. 省略duration，且计时器不在运行：计时器用其在配置中设定的初始时长重新开始。

典型应用场景来自官方文档的举例：开始一个烹饪计时器，或恢复一个你先前暂停的计时器。

前置概念：Timer 实体从哪来

timer.start的 target 是一个 Timer 实体（例如timer.laundry）。这些实体由 Timer 集成 提供，它是 Home Assistant 内置的 Helper（助手实体）之一，用于创建可以在仪表盘、脚本和自动化中管理、跨多处复用的倒计时。

Timer 实体有三种状态：idle（空闲，尚未启动或已完成/被取消）、active（正在倒计时）、paused（已暂停）。当计时器完成或被取消时会回到idle。

Timer 实体推荐通过 UI 创建：进入设置 > 设备与服务 > 助手（Helpers），选择Create helper后选择Timer。如果从configuration.yaml中移除了default_config:，需要先添加timer:配置节才能从 UI 创建。也可以用 YAML 直接定义，例如：

# configuration.yaml 示例 timer: laundry: duration: "00:01:00"

每个 timer 条目支持以下配置项（参见 Timer 集成文档）：

注意：配置了restore后，计时器会在启动/重启时恢复到正确的状态和时间；但依赖timer.finished事件的自动化，在 Home Assistant 停机期间计时器过期时不会在启动后补触发（这是 Timer 集成文档 明确列出的已知限制）。

理解这一点很重要：timer.start省略duration时“回落到配置值”，指的就是这里定义的duration。

通过用户界面使用 timer.start

如果你偏好可视化搭建自动化和脚本，Home Assistant 的 UI 会逐步引导你完成这个动作（参见 ui_header 说明：选择目标、调整选项、保存，无需 YAML 知识）。完整步骤如下：

1. 进入设置 > 自动化与场景（Automations & scenes）。
2. 打开一个已有的自动化或脚本，或选择Create automation>Create new automation。
3. 如果是新建自动化，在When部分添加一个触发器；脚本不需要触发器，它们在被其他东西调用时运行。
4. 在Then do部分，选择Add action。
5. 选择要控制的对象：在By target下方（参见下文“动作的 Targets”一节），选择你要启动的 timer。
6. 在该目标显示的动作列表中，选择Timer: Start timer。
7. （可选）设置一个用于启动计时器的Duration。
8. 选择Save。

UI 中的选项

在 YAML 中使用 timer.start

如果你直接编写 YAML，或者想确认 Home Assistant 底层实际执行的字段（参见 yaml_header 说明），YAML 中引用该动作的名称为timer.start。基础示例如下，与 官方动作文档 一致：

action: | action: timer.start target: entity_id: timer.laundry data: duration: "00:05:00"

放在完整的自动化中，它通常作为actions列表的一项，例如“检测到有人进入后开始一个 5 分钟的浴室排风计时器”：

automation: alias: "Start bathroom fan timer on motion" triggers: - trigger: state target: entity_id: binary_sensor.bathroom_motion to: "on" actions: - action: timer.start target: entity_id: timer.bathroom_fan data: duration: "00:05:00"

省略duration时（恢复暂停的计时器或按配置时长重启），写法简化为：

- action: timer.start target: entity_id: timer.laundry

YAML 中的选项

动作的 Targets

timer.start要求指定一个 target，target 就是这个动作作用的对象（参见 targets 模板）。你可以把动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对该目标背后的每一个匹配的 timer 实体执行动作。支持的目标类型：

• Entity：一个具体的 timer 实体，如timer.laundry。
• Device：属于某个设备的全部 timer 实体。
• Area：某个房间/区域内的全部 timer 实体。
• Floor：某个楼层上的全部 timer 实体。
• Label：共享某个标签的全部 timer 实体。

也可以在一个动作中混合选择不同类型的目标，例如同时添加一个具体实体和一个区域，让动作对两者同时生效。

两个容易踩坑的行为细节

来自 官方文档 “Good to know” 部分，这两条是实际使用中最容易出错的地方：

• 恢复暂停的计时器：再次启动它且不要给 duration，它会带着剩余的剩余时间继续倒计时。不要误以为省略 duration 会清零重来——只有在计时器不处于 paused 状态时，才会回落到配置时长。
• 对运行中的计时器指定新 duration：该时长会一直生效，直到计时器完成或被取消，之后才会重置回其配置值。也就是说，通过timer.start传入的时长是“本次运行的临时覆盖”，而不是永久性修改配置。

与其他 timer 动作的配合

timer.start与另外四个 timer 动作共同构成 Timer 实体的完整生命周期控制（各动作的元数据均声明了彼此的 related_actions）：

一个完整的生命周期示例：timer.start开始倒计时 → 需要中断时用timer.pause→ 继续时用不带 duration 的timer.start→ 想“加时”时用timer.change→ 想无声中止用timer.cancel，想提前触发完成逻辑用timer.finish。

配套自动化：计时器完成后的后续动作

timer.start只负责“开始”，真正产生业务效果的是与触发器的配合。Timer 集成文档 给出了两个官方自动化示例，与timer.start天然配套。

示例一：浴室排风机在计时器完成后关闭（触发器为 Timer finished）：

automation: alias: "Turn off bathroom fan when the timer finishes" triggers: - trigger: timer.finished target: entity_id: timer.bathroom_fan actions: - action: fan.turn_off target: entity_id: fan.bathroom

示例二：剩余 5 分钟时发送提醒（触发器为 Timer time remaining，remaining: "00:05:00"）：

automation: alias: "Notify when five minutes remain on the laundry timer" triggers: - trigger: timer.remaining_time_reached target: entity_id: timer.laundry options: remaining: "00:05:00" actions: - action: notify.send_message target: entity_id: notify.my_device data: message: "The laundry timer has five minutes left."

结合本文的timer.start，完整链路就是：某个事件（人离开、洗完衣服等）触发自动化 →timer.start用指定 duration 开始倒计时 →timer.remaining_time_reached在剩余 5 分钟时发通知 →timer.finished在完成时关闭排风机。

适用前提与小结

• timer.start属于 Home Assistant 内置 timer 域的动作，前提是系统中已存在对应的 Timer 实体（通过 UI 助手或configuration.yaml中的timer:配置节创建）；
• duration可选，接受秒数或HH:MM:SS字符串；省略时的行为取决于计时器当前是否处于 paused 状态；
• target 必填，且支持实体、设备、区域、楼层、标签五种目标类型并可混用；
• 对运行中的计时器传新 duration 只是本次运行的覆盖，完成后自动回到配置值。

本文全部内容以仓库内 timer.start 动作文档 为主体骨架，辅以 Timer 集成文档 的实体配置与触发器示例进行纵深补充，所有配置项、示例与行为描述均可在上述文件中核对。

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