企业官网建设流程全解析

Home Assistantmedia_player.turn_off动作详解：从 UI 配置到 YAML 自动化实战

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

media_player.turn_off是 Home Assistant 中用于关闭媒体播放器（电视、音箱、功放等）的核心动作（action）。本文以 media_player.turn_off 官方动作文档 为骨架，系统讲解该动作在 UI 与 YAML 两种场景下的完整用法、目标（Target）选择机制、适用边界，并结合 Media player 集成文档 给出可复制、可运行的自动化示例。读完本文，你将能够熟练地在自动化与脚本中精准关闭任意媒体播放器，并理解其底层目标解析逻辑与常见坑点。

动作概览：它做了什么

在 Home Assistant 中，media_player.turn_off用于关闭一个媒体播放器实体（entity），例如电视（TV）、音箱（speaker）或功放（receiver）。它的动作语义非常直接：把目标媒体播放器切换到关闭状态。

在 media_player 集成文档 中，一个媒体播放器可以处于以下状态之一：

• Off：已关闭，在重新开启前不接受任何命令；
• On：已开启，但当前具体状态未知；
• Idle：已开启且可接受命令，但当前未播放任何媒体（可能停留在待机主界面）；
• Playing：正在播放媒体；
• Paused：有活动媒体且处于暂停状态；
• Buffering：正在为开始播放做准备；
• Unavailable：实体当前不可用；
• Unknown：状态尚未确定。

调用media_player.turn_off的预期结果，就是让目标实体进入Off状态。

在 UI 中通过可视化编辑器调用

如果你更倾向于用图形化方式构建自动化和脚本，Home Assistant 会在界面中逐步引导你完成该动作的配置——选择目标、微调选项、保存即可，无需掌握任何 YAML 知识（参见 ui_header 模板）。

按照 media_player.turn_off 动作文档 中的步骤，从自动化或脚本中关闭媒体播放器的完整流程如下：

1. 进入设置（Settings） > 自动化与场景（Automations & scenes）；
2. 打开一个已有的自动化或脚本，或者选择创建自动化（Create automation） > 创建新自动化（Create new automation）；
3. 如果是新建自动化，在当……时（When）部分添加一个触发器；脚本不需要触发器，它们在被其他对象调用时运行；
4. 在然后执行（Then do）部分，选择添加动作（Add action）；
5. 选择你要控制的对象：在目标（By target）下（详见下文 目标（Targets）），选中要关闭的媒体播放器；
6. 从该目标对应的动作列表中，选择关闭媒体播放器（Turn off media player）；
7. 点击保存（Save）。

UI 中的可选参数

根据原文档说明：该动作除目标（target）之外没有额外的 UI 选项。也就是说，整个动作的配置核心就是“选谁作为目标”，没有音量、来源、状态等附加参数。

在 YAML 中使用该动作

在 YAML 中，该动作的引用名称是media_player.turn_off。原文档给出的基础示例如下：

action: media_player.turn_off target: entity_id: media_player.living_room

这段配置会把media_player.living_room关闭。

从 YAML 技术参考的角度看（参见 yaml_header 模板），该动作的字段结构非常精简：必填字段只有一个target，类型为目标对象；此外没有任何可选的data字段（如音量、来源等）。因此只要正确指定目标，动作即可生效。

完整自动化骨架

在实际自动化中，media_player.turn_off通常作为actions（或旧版action）列表中的一项出现：

automation: - alias: "关闭客厅电视" triggers: - trigger: state entity_id: zone.home to: "0" actions: - action: media_player.turn_off target: entity_id: media_player.living_room

目标（Targets）机制详解

该动作必须指定一个目标。目标就是动作的作用对象，你可以把动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会自动对该目标背后的每一个匹配的media_player实体执行动作。

根据 targets 模板，目标支持以下五种类型：

关键特性：你可以在同一次动作中混用不同类型的多个目标。例如，在同一次调用中同时添加一个具体实体和一个区域，动作就会同时作用于两者。这对于“关闭客厅电视 + 关闭客厅区域所有音箱”这类组合场景非常实用。

实战案例：全家离开时自动关闭电视

原文档提供了一个典型的自动化场景：当所有人都离开家时关闭电视，确保电视没有被留在运行状态。

• 触发器（Trigger）：所有人离开家
• 动作（Action）：关闭媒体播放器
  • 目标（Target）：客厅电视（Living room TV）

完整的 YAML 示例如下（摘自 media_player.turn_off 动作文档）：

automation: - alias: "Turn off the TV when everyone leaves" triggers: - trigger: state entity_id: zone.home to: "0" actions: - action: media_player.turn_off target: entity_id: media_player.living_room

这个示例的关键点在于：

• 触发器使用trigger: state，监听zone.home区域的状态变化；
• 当zone.home的状态变为"0"（表示家中人数为 0，即所有人都离开）时触发；
• 动作部分直接调用media_player.turn_off并指定目标实体。

你只需要把media_player.living_room替换成你自己环境的实体 ID，即可直接复制使用。Home Assistant 文档还提供了media_player.turn_on（到家开电视）的对应示例，二者可以组成“离家关电视、到家开电视”的完整联动，参见 media_player.turn_on 动作文档。

相关动作与组合使用

media_player.turn_off的动作文档在 front matter 中声明了三个相关动作（related actions）（参见 related 模板），它们与该动作配合使用效果最佳：

• media_player.turn_on：打开媒体播放器（例如电视、音箱或功放）；
• media_player.toggle：在打开与关闭之间切换媒体播放器；
• media_player.media_stop：停止媒体播放器的播放。

适用边界提示（Good to know）：根据原文档，media_player.turn_off仅对支持被关闭的媒体播放器生效。某些设备（如部分始终通电待机的流媒体播放器）可能不支持真正的断电关闭，此时调用该动作可能无效或行为因设备而异。在设计自动化时，建议先确认目标设备的集成是否实现了turn_off能力。

快速验证：在“开发者工具”中立即测试

如果你不想写一行 YAML 就验证效果，可以按 try_it 模板 的指引操作：

1. 打开设置（Settings） > 工具（Tools） > 动作（Actions）；
2. 搜索media_player.turn_off；
3. 填写字段（主要是目标实体）；
4. 点击执行动作（Perform action）。

随后观察你的真实实体是否进入 Off 状态，全程无需编写 YAML。这是排查“目标选择是否正确”“设备是否支持关闭”的最快途径。

常见问题排查

如果动作执行后没有达到预期效果，可以按以下顺序排查（参见 stuck 模板 中的社区求助建议）：

1. 确认目标实体 ID 正确：在开发者工具中确认media_player.xxx的完整实体 ID 是否存在且处于可用状态（非 Unavailable / Unknown）；
2. 确认设备支持关闭：回顾本文“适用边界”一节，检查目标设备是否实现了关闭能力；
3. 在 UI 中直接测试：使用上述“开发者工具”方式执行一次，排除 YAML 语法问题；
4. 查看日志与社区：将你调用的动作和预期行为一同描述，在 Home Assistant 社区论坛发帖求助，或使用 Discord 实时交流。

小结

media_player.turn_off是 Home Assistant 自动化体系中一个“少参数、重目标”的典型动作：它只有一个必填的target字段，却凭借实体 / 设备 / 区域 / 楼层 / 标签五类目标体系，覆盖了从“关一台电视”到“关整个楼层所有影音设备”的各类场景。配合media_player.turn_on、media_player.toggle、media_player.media_stop等关联动作，你可以快速搭建离家/到家、观影前后等媒体设备的自动开关流程。行动前记住一条核心边界——它只对支持关闭的媒体播放器生效。

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