Home Assistant Shopping List 集成指南从shopping_list.add_item动作到自动化实战【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本文以 Home Assistant 的Shopping list 集成shopping_list为切入点系统讲解其核心动作shopping_list.add_item的完整用法——包括 UI 操作路径、YAML 配置、参数说明与典型自动化场景并结合同域下的remove_item、complete_item、sort等关联动作与shopping_list_updated事件帮你快速上手自动补货、语音加购、购物后自动清理等实战能力。读完本文你将掌握该集成全部 8 个动作的调用方式并能独立写出可运行的自动化示例。一、Shopping list 集成是什么Shopping list 是 Home Assistant 内置ha_quality_scale: internal自 0.50 版本起提供的 集成用于跟踪购物清单中的待购条目。其核心能力包括侧边栏访问集成启用后清单会出现在 Home Assistant 的侧边栏中随时可打开查看与勾选仪表盘卡片可额外将 To-do list 卡片 添加到仪表盘把购物清单展示在常用页面上语音交互配合 conversation 集成可以直接用语音指令操作清单例如说Add eggs to my shopping list把鸡蛋加到我的购物清单本地推送ha_iot_class为 Local Push清单状态在本地即时更新标准 To-do 平台该集成以todo平台对外提供服务见 集成文件 中的ha_platforms: - todo。从集成配置看它走的是标准 config flowha_config_flow: true在 UI 中即可完成启用。二、动作概览8 个动作一张表掌握Shopping list 集成一共提供 8 个动作见 source/_actions 目录覆盖增、删、改、查、整表操作的完整闭环动作作用参数shopping_list.add_item向清单添加一个条目name必填stringshopping_list.remove_item移除第一个名称匹配的条目name必填stringshopping_list.complete_item将所有名称匹配的未完成条目标记为完成name必填stringshopping_list.incomplete_item将第一个名称匹配的条目重新标记为未完成name必填stringshopping_list.complete_all一次将所有条目标记为完成无shopping_list.incomplete_all一次将所有条目标记为未完成无shopping_list.clear_completed_items清空已完成条目无shopping_list.sort按名称排序全部条目reverse可选boolean默认false各动作的详细字段定义、必填性与默认值均可在 source/_actions/shopping_list.add_item.markdown 等对应文档中核对。三、核心动作详解shopping_list.add_item3.1 功能定位shopping_list.add_item的作用是向购物清单中添加一个条目。最常见的典型用法是自动补货当 Home Assistant 检测到某设备电量低时自动把电池加入购物清单避免下次购物时遗忘。它的name参数为必填字符串即要添加的条目名称添加成功后条目会出现在集成提供的唯一一份购物清单中。3.2 在 UI 中配置图形化路径若想从自动化或脚本中调用该动作可按以下步骤在 UI 中完成配置进入设置自动化与场景Automations scenes打开一个现有的自动化或脚本如果没有选择创建自动化创建新自动化如果新建的是自动化需要在当When部分添加一个触发器脚本不需要触发器——脚本由其他调用方触发执行在然后执行Then do部分选择添加动作搜索并选择添加购物清单条目Add shopping list item在名称Name字段中输入要添加的条目名称选择保存。UI 中的参数该动作在 UI 中只有一个字段——Name要添加的条目名称。3.3 在 YAML 中调用如果直接编写 YAML动作引用名为shopping_list.add_item。最基础的示例action: shopping_list.add_item data: name: MilkYAML 参数参考字段描述必填类型name要添加的条目名称是string3.4 实战自动化设备电量低时自动加购电池这是官方文档给出的经典自动化示例当遥控器等设备电池电量低于 10% 时自动把电池加入购物清单。触发器电池电量低于 10%动作添加购物清单条目完整 YAMLautomation: alias: Buy batteries when the remote is low triggers: - trigger: numeric_state entity_id: sensor.remote_battery below: 10 actions: - action: shopping_list.add_item data: name: Batteries该示例完整继承了 add_item 文档 中的用法使用numeric_state触发器监听sensor.remote_battery数值状态低于 10 时触发再调用shopping_list.add_item写入name: Batteries。3.5 快速试运行不写一行 YAML 也可以立刻验证效果打开设置工具动作Developer tools → Actions搜索该动作填入字段后点击执行动作即可在真实实体上观察清单变化参见 try_it 说明。四、Good to know使用须知使用shopping_list.add_item时请注意该集成只提供一份购物清单条目会被添加到这份唯一的清单中见 add_item 文档 的 Good to know 小节。五、关联动作完整清单操作闭环围绕add_item其余 7 个动作共同构成清单的完整生命周期管理逐个说明如下。5.1shopping_list.remove_item移除条目删除清单中第一个名称匹配的条目适合在不再需要某物时将其取走action: shopping_list.remove_item data: name: Milk参数同样只有必填的namestring。需要留意两个行为差异见 remove_item 文档若存在多个同名条目只移除第一个匹配项若想从清单勾掉但保留记录应改用shopping_list.complete_item而非删除。5.2shopping_list.complete_item标记完成不删除将所有名称匹配的未完成条目标记为已完成适合在购物时逐项勾选已完成的条目不会被再次更新action: shopping_list.complete_item data: name: Milk行为要点见 complete_item 文档条目保留在清单上不会被移除批量清空已完成条目可配合shopping_list.clear_completed_items它会触发shopping_list_updated事件且事件action属性值为complete而其他修改具体条目状态的动作action值均为update。5.3shopping_list.incomplete_item取消完成shopping_list.complete_item的反向操作将第一个名称匹配的已完成条目重新标记为未完成适合已勾掉但还需再买的场景action: shopping_list.incomplete_item data: name: Milk参数为必填的namestring。如需一次性取消全部改用shopping_list.incomplete_all见 incomplete_item 文档。5.4shopping_list.complete_all/shopping_list.incomplete_all整表标记complete_all一次把清单上所有条目标记为完成适合购物结束后统一勾选条目仍保留在清单上见 complete_all 文档incomplete_all一次把所有条目重置为未完成适合重置周期性清单如每周杂货清单让所有条目重新生效见 incomplete_all 文档。两者均无参数action: shopping_list.complete_allaction: shopping_list.incomplete_all5.5shopping_list.clear_completed_items清空已完成项移除清单中所有已完成条目只留下仍需购买的项常用于购物行程结束后自动整理清单action: shopping_list.clear_completed_items该动作没有任何参数。要点见 clear_completed_items 文档只有已完成条目会被移除未勾选的条目保持不变。实战示例离开超市时自动清理清单automation: alias: Tidy shopping list after shopping triggers: - trigger: zone entity_id: person.me zone: zone.supermarket event: leave actions: - action: shopping_list.clear_completed_items当person.me离开zone.supermarket区域时自动清除本次已勾选的条目让清单为下次购物做好准备。5.6shopping_list.sort按名称排序将所有条目按名称排序让长清单更有秩序、相关条目相邻、购物时更易查找action: shopping_list.sort可选参数reverseboolean默认false控制排序方向——为true时按 Z 到 A 降序排列action: shopping_list.sort data: reverse: true要点见 sort 文档排序只按名称进行不会将已完成条目与未完成条目分开排列UI 中对应开关为Sort reverse。六、用shopping_list_updated事件驱动自动化清单条目被修改时会触发shopping_list_updated事件事件数据中包含以下负载字段见 Shopping list 集成文档数据负载属性描述action对条目执行的操作类型取值见下表item包含被更新条目详情的字典item.id该条目的唯一 IDitem.name条目文本例如Milkitem.complete布尔值表示条目是否已标记为完成action的取值如下add新增了一个条目update条目被更新使用shopping_list.complete_item动作或整表动作时除外complete条目被完成仅通过shopping_list.complete_item动作触发remove条目被移除。典型应用新条目加入时推送通知alias: Notify on new shopping list item triggers: - trigger: event event_type: shopping_list_updated event_data: action: add actions: - action: notify.notify data: message: {{ trigger.event.data.item.name }} has been added to the shopping list data: clickAction: /shopping-list url: /shopping-list该自动化监听shopping_list_updated且action: add的事件推送通知并附带跳转/shopping-list的点击动作。此外以下操作同样会触发shopping_list_updated事件但不返回清单条目clear已完成条目被清出清单sorted清单条目按名称完成排序reorder清单条目被重新排序update_list全部条目被更新例如通过shopping_list.complete_all或shopping_list.incomplete_all动作。七、组合实战一套自动补货 购物后清理方案综合以上内容可组合出一套贴近真实生活的自动化闭环自动补货numeric_state触发器监测设备电量低于阈值时调用shopping_list.add_item添加电池语音加购借助 conversation 集成直接说把鸡蛋加到购物清单即可新增条目购物中勾选在清单界面或仪表盘 To-do list 卡片中手动勾选shopping_list.complete_item对应的 UI 操作即标记完成离店清理zone触发器监听离开超市区域调用shopping_list.clear_completed_items清空已完成项通知回执通过shopping_list_updated事件action: add让家庭成员实时收到新条目推送。八、继续深入阅读集成总览与事件定义source/_integrations/shopping_list.markdown8 个动作的完整参考source/_actions/shopping_list.add_item.markdown、source/_actions/shopping_list.remove_item.markdown、source/_actions/shopping_list.complete_item.markdown、source/_actions/shopping_list.incomplete_item.markdown、source/_actions/shopping_list.complete_all.markdown、source/_actions/shopping_list.incomplete_all.markdown、source/_actions/shopping_list.clear_completed_items.markdown、source/_actions/shopping_list.sort.markdown公共说明模板source/_includes/actions/yaml_header.mdYAML 技术参考说明、source/_includes/actions/try_it.md开发者工具试运行说明【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Home Assistant Shopping List 集成指南：从 `shopping_list.add_item` 动作到自动化实战
Home Assistant Shopping List 集成指南从shopping_list.add_item动作到自动化实战【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本文以 Home Assistant 的Shopping list 集成shopping_list为切入点系统讲解其核心动作shopping_list.add_item的完整用法——包括 UI 操作路径、YAML 配置、参数说明与典型自动化场景并结合同域下的remove_item、complete_item、sort等关联动作与shopping_list_updated事件帮你快速上手自动补货、语音加购、购物后自动清理等实战能力。读完本文你将掌握该集成全部 8 个动作的调用方式并能独立写出可运行的自动化示例。一、Shopping list 集成是什么Shopping list 是 Home Assistant 内置ha_quality_scale: internal自 0.50 版本起提供的 集成用于跟踪购物清单中的待购条目。其核心能力包括侧边栏访问集成启用后清单会出现在 Home Assistant 的侧边栏中随时可打开查看与勾选仪表盘卡片可额外将 To-do list 卡片 添加到仪表盘把购物清单展示在常用页面上语音交互配合 conversation 集成可以直接用语音指令操作清单例如说Add eggs to my shopping list把鸡蛋加到我的购物清单本地推送ha_iot_class为 Local Push清单状态在本地即时更新标准 To-do 平台该集成以todo平台对外提供服务见 集成文件 中的ha_platforms: - todo。从集成配置看它走的是标准 config flowha_config_flow: true在 UI 中即可完成启用。二、动作概览8 个动作一张表掌握Shopping list 集成一共提供 8 个动作见 source/_actions 目录覆盖增、删、改、查、整表操作的完整闭环动作作用参数shopping_list.add_item向清单添加一个条目name必填stringshopping_list.remove_item移除第一个名称匹配的条目name必填stringshopping_list.complete_item将所有名称匹配的未完成条目标记为完成name必填stringshopping_list.incomplete_item将第一个名称匹配的条目重新标记为未完成name必填stringshopping_list.complete_all一次将所有条目标记为完成无shopping_list.incomplete_all一次将所有条目标记为未完成无shopping_list.clear_completed_items清空已完成条目无shopping_list.sort按名称排序全部条目reverse可选boolean默认false各动作的详细字段定义、必填性与默认值均可在 source/_actions/shopping_list.add_item.markdown 等对应文档中核对。三、核心动作详解shopping_list.add_item3.1 功能定位shopping_list.add_item的作用是向购物清单中添加一个条目。最常见的典型用法是自动补货当 Home Assistant 检测到某设备电量低时自动把电池加入购物清单避免下次购物时遗忘。它的name参数为必填字符串即要添加的条目名称添加成功后条目会出现在集成提供的唯一一份购物清单中。3.2 在 UI 中配置图形化路径若想从自动化或脚本中调用该动作可按以下步骤在 UI 中完成配置进入设置自动化与场景Automations scenes打开一个现有的自动化或脚本如果没有选择创建自动化创建新自动化如果新建的是自动化需要在当When部分添加一个触发器脚本不需要触发器——脚本由其他调用方触发执行在然后执行Then do部分选择添加动作搜索并选择添加购物清单条目Add shopping list item在名称Name字段中输入要添加的条目名称选择保存。UI 中的参数该动作在 UI 中只有一个字段——Name要添加的条目名称。3.3 在 YAML 中调用如果直接编写 YAML动作引用名为shopping_list.add_item。最基础的示例action: shopping_list.add_item data: name: MilkYAML 参数参考字段描述必填类型name要添加的条目名称是string3.4 实战自动化设备电量低时自动加购电池这是官方文档给出的经典自动化示例当遥控器等设备电池电量低于 10% 时自动把电池加入购物清单。触发器电池电量低于 10%动作添加购物清单条目完整 YAMLautomation: alias: Buy batteries when the remote is low triggers: - trigger: numeric_state entity_id: sensor.remote_battery below: 10 actions: - action: shopping_list.add_item data: name: Batteries该示例完整继承了 add_item 文档 中的用法使用numeric_state触发器监听sensor.remote_battery数值状态低于 10 时触发再调用shopping_list.add_item写入name: Batteries。3.5 快速试运行不写一行 YAML 也可以立刻验证效果打开设置工具动作Developer tools → Actions搜索该动作填入字段后点击执行动作即可在真实实体上观察清单变化参见 try_it 说明。四、Good to know使用须知使用shopping_list.add_item时请注意该集成只提供一份购物清单条目会被添加到这份唯一的清单中见 add_item 文档 的 Good to know 小节。五、关联动作完整清单操作闭环围绕add_item其余 7 个动作共同构成清单的完整生命周期管理逐个说明如下。5.1shopping_list.remove_item移除条目删除清单中第一个名称匹配的条目适合在不再需要某物时将其取走action: shopping_list.remove_item data: name: Milk参数同样只有必填的namestring。需要留意两个行为差异见 remove_item 文档若存在多个同名条目只移除第一个匹配项若想从清单勾掉但保留记录应改用shopping_list.complete_item而非删除。5.2shopping_list.complete_item标记完成不删除将所有名称匹配的未完成条目标记为已完成适合在购物时逐项勾选已完成的条目不会被再次更新action: shopping_list.complete_item data: name: Milk行为要点见 complete_item 文档条目保留在清单上不会被移除批量清空已完成条目可配合shopping_list.clear_completed_items它会触发shopping_list_updated事件且事件action属性值为complete而其他修改具体条目状态的动作action值均为update。5.3shopping_list.incomplete_item取消完成shopping_list.complete_item的反向操作将第一个名称匹配的已完成条目重新标记为未完成适合已勾掉但还需再买的场景action: shopping_list.incomplete_item data: name: Milk参数为必填的namestring。如需一次性取消全部改用shopping_list.incomplete_all见 incomplete_item 文档。5.4shopping_list.complete_all/shopping_list.incomplete_all整表标记complete_all一次把清单上所有条目标记为完成适合购物结束后统一勾选条目仍保留在清单上见 complete_all 文档incomplete_all一次把所有条目重置为未完成适合重置周期性清单如每周杂货清单让所有条目重新生效见 incomplete_all 文档。两者均无参数action: shopping_list.complete_allaction: shopping_list.incomplete_all5.5shopping_list.clear_completed_items清空已完成项移除清单中所有已完成条目只留下仍需购买的项常用于购物行程结束后自动整理清单action: shopping_list.clear_completed_items该动作没有任何参数。要点见 clear_completed_items 文档只有已完成条目会被移除未勾选的条目保持不变。实战示例离开超市时自动清理清单automation: alias: Tidy shopping list after shopping triggers: - trigger: zone entity_id: person.me zone: zone.supermarket event: leave actions: - action: shopping_list.clear_completed_items当person.me离开zone.supermarket区域时自动清除本次已勾选的条目让清单为下次购物做好准备。5.6shopping_list.sort按名称排序将所有条目按名称排序让长清单更有秩序、相关条目相邻、购物时更易查找action: shopping_list.sort可选参数reverseboolean默认false控制排序方向——为true时按 Z 到 A 降序排列action: shopping_list.sort data: reverse: true要点见 sort 文档排序只按名称进行不会将已完成条目与未完成条目分开排列UI 中对应开关为Sort reverse。六、用shopping_list_updated事件驱动自动化清单条目被修改时会触发shopping_list_updated事件事件数据中包含以下负载字段见 Shopping list 集成文档数据负载属性描述action对条目执行的操作类型取值见下表item包含被更新条目详情的字典item.id该条目的唯一 IDitem.name条目文本例如Milkitem.complete布尔值表示条目是否已标记为完成action的取值如下add新增了一个条目update条目被更新使用shopping_list.complete_item动作或整表动作时除外complete条目被完成仅通过shopping_list.complete_item动作触发remove条目被移除。典型应用新条目加入时推送通知alias: Notify on new shopping list item triggers: - trigger: event event_type: shopping_list_updated event_data: action: add actions: - action: notify.notify data: message: {{ trigger.event.data.item.name }} has been added to the shopping list data: clickAction: /shopping-list url: /shopping-list该自动化监听shopping_list_updated且action: add的事件推送通知并附带跳转/shopping-list的点击动作。此外以下操作同样会触发shopping_list_updated事件但不返回清单条目clear已完成条目被清出清单sorted清单条目按名称完成排序reorder清单条目被重新排序update_list全部条目被更新例如通过shopping_list.complete_all或shopping_list.incomplete_all动作。七、组合实战一套自动补货 购物后清理方案综合以上内容可组合出一套贴近真实生活的自动化闭环自动补货numeric_state触发器监测设备电量低于阈值时调用shopping_list.add_item添加电池语音加购借助 conversation 集成直接说把鸡蛋加到购物清单即可新增条目购物中勾选在清单界面或仪表盘 To-do list 卡片中手动勾选shopping_list.complete_item对应的 UI 操作即标记完成离店清理zone触发器监听离开超市区域调用shopping_list.clear_completed_items清空已完成项通知回执通过shopping_list_updated事件action: add让家庭成员实时收到新条目推送。八、继续深入阅读集成总览与事件定义source/_integrations/shopping_list.markdown8 个动作的完整参考source/_actions/shopping_list.add_item.markdown、source/_actions/shopping_list.remove_item.markdown、source/_actions/shopping_list.complete_item.markdown、source/_actions/shopping_list.incomplete_item.markdown、source/_actions/shopping_list.complete_all.markdown、source/_actions/shopping_list.incomplete_all.markdown、source/_actions/shopping_list.clear_completed_items.markdown、source/_actions/shopping_list.sort.markdown公共说明模板source/_includes/actions/yaml_header.mdYAML 技术参考说明、source/_includes/actions/try_it.md开发者工具试运行说明【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
