Home Assistant 米家扫地机分区清扫：xiaomi_miio.vacuum_clean_zone 动作完全指南
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
导读
本文围绕 Home Assistant 文档库中xiaomi_miio.vacuum_clean_zone动作（Vacuum clean zone）展开，讲解如何通过 UI 与 YAML 两种方式让小米扫地机器人清扫一个或多个矩形区域，并深入说明坐标体系、repeats重复次数限制与参数校验规则。读完本文，你将能在自动化、脚本与操作面板中熟练调用分区清扫，并结合配套的vacuum_clean_segment（按房间清扫）与vacuum_goto（定点前往）动作构建完整的清扫策略。
动作概览：什么是 Vacuum clean zone
Vacuum clean zone是 xiaomi_miio 集成为小米扫地机器人提供的一项专属动作。与普通的vacuum.start（全屋清扫）不同，它允许你在地图上框出一个或多个矩形区域，并指定每个区域清扫的次数。
其核心特性（见动作定义文档）：
- 分区清扫：每个区域由一组坐标定义的矩形表示，可同时提交多个区域；
- 可设重复次数：通过
repeats指定每个区域清扫 1～3 遍； - 有目标实体：动作必须指定一个目标（如
vacuum.xiaomi_vacuum），Home Assistant 会将该动作下发到该扫地机实体。
从 xiaomi_miio 集成的底层来看，该动作对应机器人的xiaomi_clean_zone服务能力（见集成文档 Actions 一节）。在更底层的 miio 协议层面，分区清扫本质上通过app_zoned_clean命令实现（见集成文档 Zoned Cleaning 示例），该命令的参数即为"矩形坐标 + 清扫次数"。
从界面使用该动作（无需写 YAML）
在自动化或脚本中使用分区清扫的完整步骤（摘自动作文档）：
- 进入设置 > 自动化与场景（
{% my automations %}快捷入口）； - 打开现有自动化或脚本，或选择创建自动化 > 创建新自动化；
- 若新建自动化，先在When（触发条件）一节添加触发器；脚本无需触发器，由其他流程调用时执行；
- 在Then do（执行动作）一节选择添加动作；
- 在按目标（By target）下选择要控制的小米扫地机器人（目标概念详见下文"动作的目标"一节）；
- 在该目标对应的动作列表中，选择Vacuum clean zone；
- 填写Zone（区域）坐标与Repeats（重复次数）；
- 点击保存。
界面中的两个选项定义如下：
| 选项 | 说明 | 是否必填 |
|---|---|---|
| Zone | 一个区域列表，每个区域是一个由四个整数组成的列表，用于描述一个矩形的起点与终点坐标 | 是 |
| Repeats | 每个区域清扫的次数，取值范围 1～3 | 是 |
如需在不写 YAML 的情况下快速验证，可打开设置 > 工具 > 操作（Actions）（{% my developer_services %}），搜索该动作、填写字段并点击执行动作，即可在真实实体上观察效果。
在 YAML 中使用该动作
如果你直接编写 YAML 自动化或脚本，动作名为xiaomi_miio.vacuum_clean_zone。基础示例如下（摘自动作文档）：
action: xiaomi_miio.vacuum_clean_zone target: entity_id: vacuum.xiaomi_vacuum data: repeats: 1 zone: - [30914, 26007, 35514, 28807] - [20232, 22496, 26032, 26496]该示例会让vacuum.xiaomi_vacuum依次清扫两个区域各一次：先清扫第一个矩形区域，再清扫第二个矩形区域。
YAML 字段参考
| 字段 | 说明 | 必填 | 类型 |
|---|---|---|---|
zone | 区域列表；每个区域是一个由四个整数组成的列表，描述矩形起点与终点坐标 | 是 | list |
repeats | 每个区域清扫次数，1～3 的整数 | 是 | integer |
一个典型的自动化集成示例：
alias: 每天上午清扫餐桌区域 triggers: - trigger: time at: "09:00:00" actions: - action: xiaomi_miio.vacuum_clean_zone target: entity_id: vacuum.xiaomi_vacuum data: repeats: 2 zone: - [23510, 25311, 25110, 26361]坐标格式详解：[x1, y1, x2, y2]
分区清扫的坐标体系是该动作的关键。每个区域是一个四个整数的列表，格式为[x1, y1, x2, y2]（见动作文档 Good to know 一节）：
- 第一对坐标
(x1, y1)是矩形的一个角； - 第二对坐标
(x2, y2)是对角方向的另一个角。
例如[23510, 25311, 25110, 26361]表示以(23510, 25311)为起点、沿对角线扩展到(25110, 26361)的矩形区域。
几个要点：
- 坐标是地图像素坐标：该坐标系由扫地机器人自身建立，原点与充电座位置相关。与之对应，定点前往动作
xiaomi_miio.vacuum_goto的文档明确指出充电座位于(25500, 25500)（见定点前往动作文档），可据此估算其他坐标的相对位置； - 两个区域可共用一个
repeats：repeats对所有区域统一生效，无法为不同区域单独设置不同次数； - 坐标必须取自真实地图：从源码结构看，坐标值来源于机器人地图数据，随意填写无法对应实际清扫位置，需要通过地图工具获取。
如何获取分区坐标
xiaomi_miio 集成文档（Retrieving Zoned Cleaning Coordinates 一节）给出了两种主流获取方式：
- FloleVac（Android）：用小米账号登录，在同一局域网下打开地图，选择 "Zone cleanup" 并框选要清扫的区域，长按 "Cleanup"，区域坐标即被复制到剪贴板；
- RoboRock Control Center（RRCC，需 Valetudo 固件）：使用地图编辑器框选区域，可获取分区清扫所需坐标。其底层命令示例为：
action: vacuum.send_command target: entity_id: "vacuum.xiaomi_vacuum_cleaner" data: command: app_zoned_clean params: [[23084, 26282, 27628, 29727, 1]]可以看到，app_zoned_clean的参数是"矩形四坐标 + 清扫次数"，这与vacuum_clean_zone的zone+repeats语义一一对应——这也印证了该动作在底层实现上对app_zoned_clean的封装关系。
动作的目标（Targets）
该动作必须指定目标，目标即动作的作用对象。你可以将动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会针对目标背后的每一个匹配的vacuum实体执行动作（见targets 模板）：
- 实体（Entity）：单个 vacuum 实体，如
vacuum.living_room； - 设备（Device）：属于某台设备的所有 vacuum 实体；
- 区域（Area）：某个房间/区域内的所有 vacuum 实体；
- 楼层（Floor）：某一楼层的所有 vacuum 实体；
- 标签（Label）：共享同一标签的所有 vacuum 实体。
同一个动作还可以混用多种目标类型，例如同时指定一个具体实体和一个区域，让动作对两者同时生效。
与相邻动作的配合：构建完整清扫策略
vacuum_clean_zone并非孤立存在，官方将其与另外两个 xiaomi_miio 专属动作列为"相关动作"（见动作文档 front matter）：
xiaomi_miio.vacuum_clean_segment（Vacuum clean segment）：按房间编号清扫。segment 是扫地机已建图的房间，用数字标识，如segments: [1, 2]清扫 1、2 号房间；将同一编号重复列出即可多次清扫同一房间（如segments: [1, 1]清扫 1 号房间两遍）。房间编号可通过miiocli roborockvacuum --ip <ip> --token <token> get_room_mapping获取映射（见segment 动作文档与集成文档 Retrieving Room numbers 一节）;xiaomi_miio.vacuum_goto（Vacuum go to）：将扫地机送往地图上的指定坐标点，参数为x_coord与y_coord。若机器人移动中不响应，需先调用vacuum.pause或vacuum.stop再重试（见goto 动作文档）。
三个动作的适用场景对比如下：
| 动作 | 作用 | 典型参数 | 适用场景 |
|---|---|---|---|
vacuum_clean_zone | 清扫自定义矩形区域 | zone（矩形坐标列表）、repeats（1～3） | 精确清扫桌下、地毯、角落等任意矩形区域 |
vacuum_clean_segment | 按已建图的房间清扫 | segments（房间编号或编号列表） | 按房间粒度调度，如"只扫厨房" |
vacuum_goto | 前往指定坐标 | x_coord、y_coord | 定点巡查、清理污渍前的移动 |
在实际使用中，这些动作均与 xiaomi_miio 集成提供的基础 vacuum 动作（start、pause、stop、return_to_base、locate、set_fan_speed、send_command）协同工作（见集成文档 Actions 一节），例如清扫前先return_to_base回充、清扫中按需pause。
常见问题排查
- 重复次数上限：
repeats仅在 1～3 之间有效。若需要更多遍清扫，可在一个脚本中多次调用本动作，或改用vacuum_clean_segment在编号列表中重复房间号； - 机器人无响应：参考
vacuum_goto的动作说明（goto 动作文档），若机器人正在移动且不响应指令，先调用vacuum.pause或vacuum.stop，再重新下发动作； - 坐标不准确：确认坐标来自真实地图（FloleVac 或 RRCC 地图编辑器），并保证手机与扫地机处于同一网络；坐标是地图像素值而非真实米制距离；
- 区域过大：单个矩形区域建议控制在合理范围内，超大区域可能导致机器人路径规划异常，可拆分为多个小区域一次性提交。
小结
xiaomi_miio.vacuum_clean_zone是 Home Assistant 中实现小米扫地机"指哪扫哪"的核心动作：通过zone传入矩形坐标、repeats控制清扫遍数，即可在自动化与脚本中精确调度局部清扫。结合vacuum_clean_segment的房间级清扫与vacuum_goto的定点移动，你可以覆盖从"全屋"到"单房间"再到"任意矩形区域"的完整清扫粒度。深入阅读 xiaomi_miio 集成文档 还可进一步掌握坐标获取、房间编号查询与send_command底层命令等进阶技巧。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
