Home Assistant group.set 动作详解动态创建与更新 Old-Style Group 的完整指南【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本文基于 Home Assistant 官方文档仓库中的 group.set 动作文档系统讲解group.set这一服务动作它是做什么的、只适用于哪种 group、如何在 UI 与 YAML 中调用、全部选项参数的含义与互斥规则并结合文档仓库中的 Group 集成说明、模板函数文档补充其状态计算规则与周边用法。读完后你将能够在自动化或脚本中通过object_id动态创建、更新 old-style group 的成员与行为并正确组合group.remove、group.reload完成生命周期管理。1. group.set 是什么只面向 old-style group 的创建/更新服务group.set用于创建一个新的 old-style group或更新一个已存在的 old-style group。你通过object_id定位 group并可设置它的名称name、图标icon、成员列表entities等以及状态聚合行为all。文档中有两条必须牢记的边界它只作用于 old-style group——即通过configuration.yaml中顶层group:配置段或通过本动作创建的那类通用型 group。它不能用于在 UI 中新建的 new-style group即 Settings Devices services Helpers 里创建的 Light group、Switch group、Sensor group 等 Helper 型 group。关于两种 group 的关系文档仓库中 Group 集成文档 的 Old style groups 一节有权威说明old-style group 是 Home Assistant 早期用于在界面上视觉归组实体的机制如今虽不再被官方推荐使用官方建议改用按域划分的 Helper group但仍然受支持它的特点是更通用可组合更多实体域如climate、device_tracker、vacuum等 20 余个域但也更受限只能通过 YAML 或本动作创建且 UI 自定义能力有限。group.set正是这类 group 的编程式创建/更新入口典型使用场景是在自动化中按条件动态拼装一组实体供后续expand()展开、模板引用或homeassistant.turn_on/turn_off整组操作。2. 在 UI 中使用从自动化/脚本里添加 Group: Set group如果偏好可视化操作按文档给出的步骤完成进入Settings Automations scenes。打开一个已有自动化或脚本或选择Create automation Create new automation。若是新建自动化在When区域添加触发器脚本不需要触发器它由其他东西调用时运行。在Then do区域选择Add action。在搜索框中搜索并选择Group: Set group。填入Object ID及其他要设置的选项。选择Save。注意该动作不支持 targets。在 UI 中你不会看到选择区域、设备、实体或标签的提示框——它只接受data里的选项参数。2.1 UI 中的可选项选项说明Object IDgroup 的对象 ID用于拼成实体 ID格式为group.object_idNamegroup 的名称Icongroup 的图标名Entitiesgroup 成员的完整列表不能与Add entities或Remove entities组合使用Add entities要添加到 group 的成员不能与Entities或Remove entities组合使用Remove entities要从 group 移除的成员不能与Entities或Add entities组合使用All启用后只有当所有成员都为 on 时 group 才为 on3. 在 YAML 中使用 group.set在 YAML 中该动作写作action: group.set。原文档给出的基础示例如下action: | action: group.set data: object_id: my_group name: My group entities: - light.living_room - light.kitchen这个调用会创建或更新 groupgroup.my_group并把它设置为包含两个灯光成员的组。由于是创建或更新语义对已存在的group.my_group该调用会直接覆盖其成员与属性。3.1 选项参数完整参考YAML参数必填类型说明object_id是stringgroup 的对象 ID用于拼成实体 ID格式为group.object_idname否stringgroup 的名称icon否stringgroup 的图标名entities否listgroup 成员的完整列表不能与add_entities或remove_entities组合add_entities否list要添加到 group 的成员不能与entities或remove_entities组合remove_entities否list要从 group 移除的成员不能与entities或add_entities组合all否boolean启用后只有当所有成员都为 on 时 group 才为 on默认false3.2 成员管理三参数的互斥规则重点entities、add_entities、remove_entities三个参数一次调用只能使用其中一个它们不能组合。从文档的表述可以推断其语义分工entities全量替换——把 group 的成员精确重置为你列出的这一组实体add_entities增量追加——在现有成员基础上加入新实体remove_entities增量删除——从现有成员中剔除指定实体。这种全量 vs 增量的区分在自动化里很实用例如夜间自动化先用entities建立客厅夜灯组白天回家时再对同一个object_id用add_entities追加快照传感器而无需重新枚举整个列表。4. 典型实战在自动化中完成 group 的完整生命周期结合本动作的两个关联动作一个完整的动态 group 使用模式如下以下均为文档中已存在的动作group.remove、group.reloadautomation: - alias: 按时间动态重组夜间灯光组 trigger: - time: at: 19:00 action: - action: group.set data: object_id: night_lights name: Night lights icon: mdi:lightbulb-multiple entities: - light.hallway - light.bedroom - light.bathroom all: false - alias: 早晨清理动态 group trigger: - time: at: 07:00 action: - action: group.remove data: object_id: night_lights要点说明group.remove只移除由group.set创建的 old-style group即带auto: true属性的那类不会移除你在 YAML 配置里写死的 group若你修改的是configuration.yaml中的 group 配置应改用group.reload让改动免重启生效它没有任何参数直接action: group.reload即可。5. old-style group 的状态计算与all参数all参数控制 group 状态如何由成员状态聚合而来。在all: false默认下只要有任一成员ongroup 即为on在all: true下必须全部成员ongroup 才on。old-style group 可以对其成员所在域计算状态。Group 集成文档 列出了受支持的域清单alert、alarm_control_panel、automation、binary_sensor、calendar、climate、cover、device_tracker、fan、humidifier、input_boolean、light、lock、media_player、person、plant、remote、script、switch、vacuum、water_heater并明确声明其他平台域不受支持且未来也不会加入。当成员实体只有单一on/off两态时group 状态直接按on/off计算对少数具有双值语义的域映射关系为域视为 on视为 offdevice_trackerhomenot_homecoveropenclosedlockunlockedlockedpersonhomenot_homemedia_playerokproblem当 group 混合了多态域如climate、media_player与两态域时group 状态统一为on/off。需要留意如果 group 中包含不受支持域的实体系统将无法计算该 group 的状态其状态会一直为 unknown——这类 group 仍可配合expand()或homeassistant.turn_on/turn_off使用但不能指望它有可用状态。6. 与auto属性、expand() 及整组操作的关系原文档 Good to know 一节的两条要点结合仓库其他文档展开如下auto: true属性标记。通过group.set创建或更新的 group 会带有一个恒为true的auto属性。Group 集成文档 的 old-style group Attributes 表格也印证了这一点old-style group 有三个属性——entity_id成员实体 ID 列表、order创建顺序整数从 0 开始、auto布尔Only appears in groups that were created with thesetaction即只出现在由set动作创建的 group 上。这解释了为什么group.remove能精确区分动态 group与YAML 静态 group它只移除带auto: true标记的 group。expand()模板函数。对于状态为 unknown 的 group文档明确建议配合expand()函数使用它把 group 展开成去重、按实体 ID 排序的独立实体 State 对象列表支持递归展开嵌套 group。典型用法例如在模板中统计组内亮灯数量{{ expand(group.night_lights) | selectattr(state, eq, on) | list | count }}整组开关。old-style group 本身可被homeassistant.turn_on/homeassistant.turn_off这类通用动作整体操作这也是动态建组 → 整组操作 → 动态删组模式的最后一环。7. 验证与排错建议在开发者工具中直接试跑打开Settings Tools Actions搜索Group: Set group填好Object ID等字段后点Perform action即可在不写一行 YAML 的情况下在真实实例上验证效果原文档 Try it yourself 一节的标准做法。确认创建成功调用后检查实体group.object_id是否存在、entity_id属性是否列出你预期的成员、auto属性是否为true。常见误区把entities与add_entities混用——一次调用只能三选一期望用group.set修改 UI Helper group——它只作用于 old-style group期望修改 YAML 里的 group 后立即生效——那是group.reload的职责不是group.set。8. 关联动作group.remove按object_id移除 old-style group是group.set的配对清理动作group.reload免重启重新加载 YAML 中配置的 groups、entities 与 notify services适合修改configuration.yaml后使用。本文全部结论均出自文档仓库中的 source/_actions/group.set.markdown、source/_integrations/group.markdown、source/_actions/group.remove.markdown、source/_actions/group.reload.markdown 与 source/_template_functions/expand.markdown。若你的 Home Assistant 版本界面文案与上述步骤略有出入以 Group 集成文档 对 old-style group 的定义为准。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
