Home Assistant `media_player.clear_playlist` 操作完全指南：清空媒体播放器播放列表

Home Assistantmedia_player.clear_playlist操作完全指南：清空媒体播放器播放列表

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

media_player.clear_playlist是 Home Assistant 中media_player域下的一个标准操作（action），用于将媒体播放器当前队列（queue）或播放列表中的所有条目一次性移除。本文以 关联文档 为骨架，结合仓库中 Sonos 集成 与 HEOS 集成 的实际用法，完整讲解该操作的 UI 配置、YAML 写法、目标（target）选择机制以及真实自动化场景，读完后你将能独立在自动化与脚本中正确调用它，并规避空队列报错等边界问题。

操作概述：它做什么、何时用

该操作的作用非常聚焦：删除一个媒体播放器播放列表或队列中的所有条目。官方文档的定位是：

Use this action to remove all items from a media player's playlist or queue.

从文档 front matter 可知它的基本身份信息：

• Action 名称：media_player.clear_playlist
• 所属域（domain）：media_player
• 关联操作：media_player.media_stop（停止播放）、media_player.play_media（播放媒体）

典型使用场景包括：

• 夜间定时清空队列，让第二天从干净的状态开始；
• 在批量加入新曲目之前清空旧队列（见下文 Sonos 的"搜索并重建队列"示例）；
• 切换播放源或结束某个收听会话时清理遗留的排队内容。

需要特别强调文档中的一条重要说明（"Good to know" 部分）：

This action only works with media players that support clearing the playlist.

即只有底层设备/集成实现了清空播放列表能力时该操作才会生效，并非所有media_player实体都支持。因此调用前应确认目标设备能力，或依赖下文介绍的continue_on_error机制做容错。

在 UI 中配置：自动化与脚本里的操作步骤

文档给出了在用户界面中添加此操作的标准流程（对应仓库模板 source/_includes/actions/ui_header.md）：

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

需要留意的是：此操作在 UI 中没有除目标（target）之外的任何额外选项（原文："This action has no additional options beyond the target."）。这意味着它的全部行为都由"作用于哪个实体"决定，配置极其简单。

YAML 用法：基础示例与完整参数

在 YAML 中调用时，操作名写作media_player.clear_playlist。文档给出的基础示例：

action: media_player.clear_playlist target: entity_id: media_player.living_room

这段配置会清空media_player.living_room上的播放列表。与 UI 一致，该操作在 YAML 中同样没有除目标之外的任何附加参数（"This action has no additional YAML options beyond the target."），所以你不需要提供data块，只有action与target两个键。

更完整地，在一个自动化中它通常长这样（来自文档的"深夜清空队列"示例）：

automation: - alias: "Clear the queue at the end of the night" triggers: - trigger: time at: "02:00:00" actions: - action: media_player.clear_playlist target: entity_id: media_player.living_room

• Trigger（触发器）：时间型触发器，每天 02:00 触发。
• Action（操作）：清空"Living room speaker"（客厅音箱）的播放列表，次日从全新状态开始。

目标（Targets）：操作的作用对象

该操作必须指定目标（"This action requires a target"）。目标是操作的客体，你可以把操作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对目标背后所有匹配的media_player实体执行该操作。仓库模板 source/_includes/actions/targets.md 中定义了五种目标类型：

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

你还可以在同一操作中混用不同类型的多个目标，例如同时指定一个具体实体和一个区域，让操作同时作用于两者。借助这种机制，一条media_player.clear_playlist就能批量清空多个音箱、多个房间的队列，而无需为每个实体单独写一条。

真实场景：Sonos 集成中的"搜索 → 清空 → 重建队列"

在仓库的 Sonos 集成文档 source/_integrations/sonos.markdown 中，media_player.clear_playlist被用于一个非常实用的组合流程：搜索本地音乐库中所有匹配的曲目、清空现有队列、逐条加入并播放。

这个示例展示了该操作与media_player.search_media、media_player.play_media的典型协作方式：

actions: - action: media_player.search_media data: search_query: "love" media_content_type: track response_variable: results target: entity_id: media_player.kitchen - action: media_player.clear_playlist target: entity_id: media_player.kitchen - variables: search_length: "{{ results['media_player.kitchen']['result']|count }}" - repeat: sequence: - action: media_player.play_media target: entity_id: media_player.kitchen data: enqueue: add media: media_content_id: >- {{ results['media_player.kitchen']['result'][repeat.index - 1]['media_content_id'] }} media_content_type: >- {{ results['media_player.kitchen']['result'][repeat.index - 1]['media_content_type'] }} until: - condition: template value_template: '{{search_length == repeat.index}}' - action: sonos.play_queue target: entity_id: media_player.kitchen

流程拆解：

1. media_player.search_media在 Sonos 本地音乐库中搜索所有匹配 "love" 的曲目，结果存入response_variable: results（搜索范围仅限本地音乐库，流媒体服务如 Spotify、Tidal 不包含在内，且media_content_type支持track、album、artist、composer、genre、playlist等取值）。
2. media_player.clear_playlist先清空厨房音箱当前队列，保证新队列不混入旧内容。
3. repeat循环逐条用enqueue: add把搜索结果追加进队列。
4. 最后调用sonos.play_queue开始播放整条队列。

这个示例同时印证了文档中"操作只对支持清空播放列表的播放器生效"这一说明——Sonos 集成明确实现了该能力，因此在此组合中它是安全可靠的。

边界与容错：HEOS 集成中的空队列报错

并非所有实现都允许无条件清空。仓库的 HEOS 集成文档 source/_integrations/heos.markdown 中明确记录了一个容易踩坑的行为：

Actions may fail if they cannot be processed by the HEOS device. For example, attempting to callmedia_player.clear_playlistwhen the queue is empty will result in an error. To prevent this from halting a script or automation, setcontinue_on_error: truein the action call.

也就是说，HEOS 设备在队列为空时调用media_player.clear_playlist会直接报错。文档建议的规避方式是给该操作加上continue_on_error: true，防止单个操作失败中断整个脚本或自动化：

actions: - action: media_player.clear_playlist target: entity_id: media_player.denon_avr continue_on_error: true

关于continue_on_error的语义，仓库的脚本文档 source/_docs/scripts.markdown 说明：它适用于所有操作，默认值为关闭；设置后当该操作失败时，脚本/自动化不会中止，而是继续执行后续步骤。需要注意的是，它不会掩盖配置错误本身（例如目标实体不存在这类问题仍会被处理）。这一容错模式对任何"设备不支持清空"或"队列为空"的播放器都具有普适参考价值。

与关联操作的组合：停止、播放与清空

该文档 front matter 声明了两个关联操作，理解它们的差异有助于设计正确的控制序列：

• media_player.media_stop（见 source/_actions/media_player.media_stop.markdown）：停止播放，只中断当前播放，并不删除队列内容。
• media_player.play_media（见 source/_actions/media_player.play_media.markdown）：播放指定媒体，可向队列添加内容（配合enqueue参数）。

典型的完整控制序列可以是：media_player.media_stop停止当前播放 →media_player.clear_playlist清空遗留队列 →media_player.play_media载入新的播放内容。三者的关注点分别是"停止声音""清空排队""开始新内容"，组合使用即可覆盖媒体播放的完整状态机切换。

常见问题与排障思路

综合文档与集成源码，遇到"操作不生效"时可依次排查：

1. 设备能力：确认目标播放器支持清空播放列表（可查阅对应集成文档，如 Sonos、HEOS 均支持；不支持的实体该操作会被忽略或报错）。
2. 目标是否正确：确认target.entity_id存在且是media_player域实体；需要批量操作时改用设备、区域、楼层或标签目标。
3. 空队列报错：HEOS 等集成在队列为空时调用会报错，为该操作加continue_on_error: true避免中断整个流程。
4. 与其他操作协作：清空操作本身不改变播放状态，若期望"停止并清空"，需配合media_player.media_stop使用。

总结

media_player.clear_playlist是一个轻量但边界明确的media_player操作：它只负责移除播放列表/队列中的所有条目，没有除目标之外的任何参数，因此正确选择目标和确认设备能力是使用的关键。通过 UI 操作添加流程、YAML 基础示例、Sonos 的"搜索—清空—重建队列"实战组合以及 HEOS 的空队列容错方案，你可以在自动化与脚本中安全地管理任何支持该能力的媒体播放器的播放队列。

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