Home Assistant collection_image.shuffle 动作实战为图片实体随机轮换媒体库图片【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读collection_image.shuffle是 Home Assistant 2026.9 新增的collection_image收藏图片域动作用于从集成配置时选定的媒体源目录中随机挑选一张新图片并更新到对应的 image 实体上。本文将围绕该动作的完整用法展开从集成初始化、UI 图形化配置到 YAML 自动化/脚本调用、目标Target语义再到把图片实体用作前端图片卡片与仪表盘背景的动态切换方案最后给出可验证的源码与变更记录依据。动作概览它做了什么根据 collection_image.shuffle 动作文档 的定义该动作的官方描述是Update the image entity to a random image from the configured media.即从配置好的媒体目录中随机选择一张新图片更新到 collection_image 图片实体上。每次调用该动作实体呈现的图片都会变化从而实现“图片轮换”效果。该动作属于collection_image域对应 Home Assistant 官方动作服务collection_image.shuffle。结合 Collection image 集成文档 可以确认其工作原理该集成在配置流程中让你选择一个媒体源目录随后会创建一个 image 实体文章稍后会给出真实示例实体名实体当前展示哪张图由该目录中随机选中的一张图片决定。shuffle动作就是这个“随机重选”过程的触发器。前置条件先完成 Collection image 集成配置在使用shuffle动作之前你必须已经有一个可用的 collection_image 实体。参照 Collection image 集成文档集成是支持配置流程ha_config_flow: true的在 frontmatter 元数据中可以看到它的关键属性ha_release: 2026.9—— 随 2026.9 版本发布ha_domain: collection_imageha_platforms: image—— 该集成只提供 image 平台ha_integration_type: serviceha_quality_scale: bronze。配置流程中只有一个必填项配置项说明Media媒体目录图片将被从中选出的媒体文件夹集成假定你已经配置好了本地媒体源或其他提供媒体源的集成。在媒体浏览器弹窗中导航到存放目标图片的文件夹点击对话框顶部的Pick选择该文件夹最后点击Create完成配置流程。官方文档给出了一个具体实例如果你选择的文件夹名为Family Pictures配置完成后会创建一个名为image.family_pictures_collection的实体。本文后面所有示例都将以该实体为操作对象。在 UI 中调用该动作可视化配置如果你倾向用可视化方式构建自动化和脚本ui_header 模板 说明了 Home Assistant 会逐步引导你完成整个配置过程——选择目标、微调选项、保存即可无需掌握 YAML。官方动作文档给出了完整步骤进入SettingsAutomations scenes设置 自动化与场景。打开一个已有的自动化或脚本如果是新建选择Create automationCreate new automation创建自动化 创建新自动化。若是新建自动化在When何时部分添加一个触发器。脚本不需要触发器它们在被其他内容调用时才运行。在Then do然后执行部分选择Add action添加动作。选择要控制的对象。在By target按目标详见下文“动作的目标”下选择你的 collection_image 实体。在该目标显示的动作列表中选择Shuffle。点击Save保存。UI 中的选项该动作在 UI 中没有任何额外选项——你只需要指定目标实体动作即可执行。这也是它“简单直接”的原因随机选图逻辑完全由集成内部完成。在 YAML 中调用该动作自动化与脚本如果你直接编写 YAML或希望精确了解 Home Assistant 底层行为可以按 yaml_header 模板 所提示的字段结构来写。官方基础示例如下action: | action: collection_image.shuffle target: entity_id: image.my_photos其中action固定为collection_image.shuffletarget.entity_id目标图片实体这里以image.my_photos为例实际请替换为你自己的 collection_image 实体如前面提到的image.family_pictures_collection。在自动化完整上下文中的典型写法automation: - alias: Shuffle collection image hourly trigger: - platform: time_pattern hours: /1 action: - action: collection_image.shuffle target: entity_id: image.family_pictures_collection动作的目标Targets语义根据 targets 模板该动作必须指定目标target且支持五种目标类型。Home Assistant 会针对目标背后每一个匹配的 image 实体执行动作实体Entity单个指定 image 实体例如image.living_room设备Device属于某台设备的每一个 image 实体区域Area某个房间/区域内的每一个 image 实体楼层Floor某一楼层上的每一个 image 实体标签Label共享某个标签的每一个 image 实体。你还可以在同一次动作中混合不同类型的多个目标例如同时指定一个具体实体和一个区域让动作同时对两者生效。这一点对多显示器、多房间图片轮换场景非常实用。实战扩展动态图片卡片与仪表盘背景这是collection_image.shuffle最典型的两类落地用法均出自 Collection image 集成文档 的“Example usage”一节与本文主题强相关。用法一图片卡片随点随换在仪表盘上创建一张 picture图片卡片让卡片直接引用该 image 实体再为卡片配置点击动作tap action调用collection_image.shuffle实现“每次点击卡片就轮换一张图”type: picture image_entity: image.family_pictures_collection tap_action: action: perform-action perform_action: collection_image.shuffle target: entity_id: image.family_pictures_collection要点说明image_entity直接指向 collection_image 实体卡片即显示该实体当前随机选中的图片每当调用shuffle服务集成会重新随机选图仪表盘上的卡片会自动更新tap_action使用perform-action与perform_action: collection_image.shuffle的组合目标指向同一实体实现点击轮换。用法二作为仪表盘动态背景另一种思路是不直接以实体为目标而是在媒体浏览器中选择与实体对应的元素在仪表盘视图背景选项中点击Select from media从媒体选择再次打开媒体浏览器选择顶层Image文件夹在内部找到名为Family Pictures Collection的条目名称与你的实体对应。这样图片实体就会作为视图背景呈现同样可以通过任意自动化或你选择的 UI 按钮动态调用shuffle进行切换。验证与排障从变更记录与测试看实现事实仓库中的版本变更记录为上述用法提供了实现级证据source/changelogs/core-2026.9.markdown 记录Add collection_image.shuffle service由 codeownerkarwosts提交同文件还记录了后续修复Fix collection_image unavailable handling说明集成会处理实体不可用unavailable时的状态行为source/_posts/2026-09-02-release-20269.markdown 的 2026.9 版本发布说明中也收录了 [Collection image] 这一新条目。如果你在调用动作后发现图片未变化可以按以下顺序排查确认媒体目录非空且包含可被识别的图片格式确认目标实体确实是 collection_image 域创建出的 image 实体而非普通 image 平台实体在SettingsToolsActions设置 工具 动作中搜索collection_image.shuffle填写目标后点击Perform action直接试运行——这是 try_it 模板 推荐的无代码验证方式无需编写任何 YAML 即可观察实际效果。小结collection_image.shuffle是一个零配置选项、面向目标的极简动作集成配置时确定媒体池调用时随机重选一张图片。它的核心价值在于把“媒体库随机图”与前端展示图片卡片、动态背景打通配合target的实体/设备/区域/楼层/标签多级语义可以轻松构建多房间、多屏位的图片轮换体系。无论是 UI 可视化配置还是 YAML 自动化官方文档动作文档 与 集成文档都已给出可直接照做的完整步骤与示例。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考