企业官网建设流程全解析

Home Assistant timer.pause 动作详解：暂停计时器并保留剩余时间的完整实践

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

本文基于 Home Assistant 官方文档仓库中的 timer.pause 动作参考页展开，系统讲解如何在自动化与脚本中暂停一个正在运行的计时器（timer）并保持其剩余时间。读完后，你将掌握timer.pause的 UI 与 YAML 两种配置方式、动作的目标（target）规则，以及如何配合timer.start恢复计时、与timer.cancel/timer.finish/timer.change组成完整的计时器控制方案，并理解计时器实体idle/active/paused状态模型对暂停行为的影响。

1. timer.pause 动作是什么

timer.pause用于暂停一个正在运行的计时器（running timer），暂停后剩余时间会被保留（the remaining time is kept），因此可以稍后继续计时。官方文档给出的典型场景是：在组间休息时短暂中断一个健身倒计时（pausing a workout timer between sets）。

在 YAML 中该动作名为timer.pause，基本用法如下（摘自 timer.pause 文档）：

action: | action: timer.pause target: entity_id: timer.laundry

几个关键事实：

• 该动作没有任何选项（"This action has no options"）——UI 中没有可填参数，YAML 中也不需要data字段，只需要通过target指定要暂停哪个计时器；
• 它的作用对象是timer域下的实体，例如timer.laundry；
• 与计时器的其他生命周期动作配套：官方文档在 front-matter 中声明了四个相关动作——timer.start、timer.cancel、timer.finish、timer.change。

2. 在 UI 中配置 timer.pause 的步骤

官方文档给出的图形界面操作步骤如下（适用于自动化或脚本的编辑流程）：

1. 进入Settings>Automations & scenes（设置 > 自动化与场景）；
2. 打开一个已有的自动化或脚本，或选择Create automation>Create new automation；
3. 如果是新建自动化，先在When部分添加一个触发器（trigger）。脚本不需要触发器——它们由别的东西调用时才会执行；
4. 在Then do部分，点击Add action；
5. 选择要控制的对象。在By target下（见下文动作的目标）选择要暂停的计时器；
6. 在针对该目标显示的动作列表中，选择Timer: Pause timer；
7. 点击Save。

由于该动作没有选项，UI 配置到此即可完成。

3. YAML 写法与目标规则

3.1 基本示例

在 YAML 中将此动作写为timer.pause：

automation: alias: "Pause laundry timer between sets" triggers: - trigger: time at: "18:30:00" actions: - action: timer.pause target: entity_id: timer.laundry

核心结构只有两层：

3.2 动作的目标（Targets）

根据仓库中 actions 文档共用的 targets 片段，timer.pause要求指定一个目标，目标可以是以下任意一种，Home Assistant 会对目标背后所有匹配的 timer 实体执行该动作：

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

同一个动作中还可以组合多种目标类型——例如同时添加一个具体实体和一个区域，让动作同时对两者生效。

4. 状态模型：为什么"剩余时间保留"能成立

理解timer.pause的行为，需要先看计时器实体的状态模型。根据 Timer 集成文档，Timer 集成（自 0.57 版本起内置）提供的 timer 实体具有以下特性：

• States:idle、active、paused；
• Remarks: 计时器在结束（finish）、被取消（cancel）或尚未启动时回到idle；
• 与自动化的for选项不同，timer 是独立的实体，可以在仪表板中查看、管理，并在多个自动化之间复用同一个倒计时。

由此可以推断出暂停的完整状态流转：timer.pause只在active状态下有意义，执行后实体进入paused状态并冻结剩余时间；计时器在paused期间不会倒计时，也不会触发timer.finished事件。

4.1 恢复：不带 duration 的 timer.start

官方文档在 "Good to know" 中给出了一条关键用法：

To continue a paused timer, use the Start a timer action without a duration. It resumes with the time that was left.

即：要恢复一个已暂停的计时器，使用不带duration的 timer.start 动作，它会以暂停时剩余的时间继续运行。timer.start的完整语义（来自 timer.start 文档）：

• 省略duration时：计时器使用其配置的初始时长，或继续一个暂停中计时器的剩余时间；
• 若传入duration（秒数或HH:MM:SS格式字符串）：以该新时长启动/重启计时器；
• 给一个正在运行的计时器指定新duration时，该时长生效到计时结束或被取消，之后会重置回配置的时长。

# 恢复已暂停的计时器（保留剩余时间） action: | action: timer.start target: entity_id: timer.laundry

5. 与其他 timer 动作的对比与组合

timer.pause与同域其他动作的边界，是正确使用它的核心。以下对比基于仓库中四个相关动作的文档：

从这几份文档的 "Good to know" 段落可以提炼出清晰的决策路径：

• 想暂时中断、稍后继续→timer.pause，之后用不带 duration 的timer.start恢复；
• 想终止且不希望下游逻辑（如关排风扇、发通知）被执行→timer.cancel（不触发timer.finished）；
• 想终止并希望触发"计时完成"的全部下游动作→timer.finish（会触发timer.finished事件）；
• 想延长或缩短正在进行但不暂停的倒计时→timer.change（注意：无法把计时器延长到超过其启动时设定的时长；且计时器必须处于运行中该动作才有效）。

5.1 完整实战：可暂停的洗衣倒计时提醒

组合 timer 的触发器与动作可以构造"可暂停"的体验。例如洗衣计时器剩 5 分钟时通知你，中途需要时一键暂停，恢复时从剩余时间继续：

# 通知自动化：剩余 5 分钟时提醒 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 集成文档中给出的"剩 5 分钟提醒"示例一致。配套的暂停/恢复动作可放在两个按钮或两个脚本中：

# 脚本：暂停 script: pause_laundry: sequence: - action: timer.pause target: entity_id: timer.laundry resume_laundry: sequence: - action: timer.start # 不带 duration，恢复剩余时间 target: entity_id: timer.laundry

计时完成后由 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

timer.finished触发器在倒计时归零或执行Finish timer动作时触发；其事件数据中包含finished_at时间戳，可供For at least（YAML 中的for选项）使用。

6. 前置条件、边界与注意事项

• 计时器实体必须先存在：timer.pause的 target 指向一个 timer 实体，而实体需要先创建。推荐方式是在 UI 的Settings>Devices & services>Helpers中选择Create helper>Timer；如果已从configuration.yaml移除default_config:，需先添加timer:节点。YAML 方式示例（来自 Timer 集成文档）：

  # Example configuration.yaml entry timer: laundry: duration: "00:01:00"

  可配置项包括：name（友好名称）、duration（初始时长，秒或HH:MM:SS，默认 0）、icon（状态卡图标）、restore（默认 false）。

• restore选项与暂停状态的关系：Timer 集成文档明确说明，开启restore: true后，"active 和 paused 计时器会在 Home Assistant 启动或重启后恢复"（active and paused timers are restored after Home Assistant starts or restarts）。也就是说，若希望重启后暂停中的计时器仍保持暂停且剩余时间不丢，需要显式开启该选项。

• 停机期间的完成事件不会补发：官方文档在 Known limitations 中声明，如果计时器在 Home Assistant 未运行时到达终点，使用Timer finished触发器的自动化在启动后不会运行。这同样适用于"暂停后跨重启"的场景设计——恢复后继续计时的前提是restore生效。

• timer.pause无选项意味着无参数可错：该动作只有 target，不存在data配置；如果你发现暂停不生效，应检查目标实体当前是否处于active状态，以及 target 选择是否命中了正确的 timer 实体（结合上文目标规则核对 entity/device/area/floor/label）。

• 社区支持：仓库文档的通用 "Still stuck?" 板块提示，Home Assistant 社区（Discord、社区论坛、Reddit 的 r/homeassistant）可以快速解答动作行为类问题；也可以直接描述你的目标，让 AI 助手帮你挑选合适动作。

7. 小结

timer.pause是 Home Assistant timer 域中最轻量的动作：无参数、以 target 指定实体、冻结剩余时间并进入paused状态。它的价值在于与整个 timer 生命周期体系（start / pause / cancel / finish / change）以及timer.finished、timer.remaining_time_reached等触发器的组合——文档仓库中 timer.pause、timer.start、timer.cancel、timer.finish、timer.change 与 Timer 集成共同构成了一套可暂停、可恢复、事件驱动的倒计时控制方案，适用于洗衣、烹饪、健身、通风等任何需要"中途暂停、稍后继续"的自动化场景。

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