Lovelace Xiaomi Vacuum Map Card 实战指南：解决地图控制与配置优化的完整解决方案

Lovelace Xiaomi Vacuum Map Card 是 Home Assistant 生态中一款强大的地图控制插件，为小米、Roborock 等品牌扫地机器人提供直观的地图交互界面。本文针对用户在使用过程中遇到的显示异常、功能故障、性能优化等核心问题，提供系统化的排查思路和实操解决方案，帮助你充分发挥卡片的地图控制功能。

显示异常类问题解决方案

如何解决地图无法加载的问题

你是否遇到过添加卡片后地图区域始终显示空白的情况？这种问题通常与地图源配置或坐标转换有关，可按以下步骤排查：

✓ 检查地图源配置
确保在卡片配置中正确设置 map_source 参数。若使用摄像头作为地图源，需确认 Xiaomi Cloud Map Extractor 组件已安装并正常生成地图数据。基础配置示例：

map_source:
  camera: camera.xiaomi_cloud_map_extractor  # 摄像头地图源
  # 或使用图片地图源
  # image: /local/floor_plan.png

✓ 验证坐标校准数据
坐标校准（将地图像素位置转换为机器人实际坐标的过程）是地图显示的关键。使用图片地图源时，必须提供至少3个校准点：

calibration_source:
  calibration_points:
    - vacuum: {x: 25500, y: 25500}  # 机器人坐标
      map: {x: 466, y: 1889}         # 对应地图像素坐标

✓ 执行缓存清理
浏览器可能缓存旧地图数据，按 Ctrl+Shift+R 执行强制刷新，或在 Home Assistant 开发者工具中清除前端缓存。

适用场景：所有地图源类型，特别适用于初次配置或地图文件更新后。

如何解决多地图切换失效问题

当配置了多个楼层地图但无法切换时，通常是预设配置不完整导致：

✓ 检查预设配置结构
确保每个预设包含独立的地图源和校准源：

additional_presets:
  - preset_name: 一楼
    map_source: {camera: camera.map_floor1}
    calibration_source: {camera: true}
  - preset_name: 二楼
    map_source: {camera: camera.map_floor2}
    calibration_source: {camera: true}

✓ 验证实体状态
在开发者工具中检查 sensor.vacuum_map_preset 实体状态，确认预设切换指令已正确触发。

适用场景：多楼层住宅或需要分区控制的场景。

功能故障类问题解决方案

如何解决区域选择无响应问题

框选清洁区域后机器人无动作？这通常与地图模式配置或坐标映射有关：

✓ 确认地图模式配置
检查是否加载了区域清洁模板：

map_modes:
  - template: vacuum_clean_zone  # 确保包含区域清洁模板
    selection_type: MANUAL_RECTANGLE  # 启用手动矩形选择

✓ 测试基础指令通信
通过开发者工具直接调用服务验证机器人通信：

service: vacuum.send_command
target:
  entity_id: vacuum.xiaomi_vacuum
data:
  command: app_zoned_clean
  params: [[25500,25500,26500,26500,1]]  # 测试区域坐标

适用场景：所有支持区域清洁的机器人型号。

如何解决升级到 v2.x 后配置失效问题

从 v1.x 升级后配置失效，主要是配置结构变化导致：

✓ 更新配置结构
v2.x 采用新的嵌套配置结构，关键变化对比：

v1.x 旧配置：

map_image: /local/map.png
camera_calibration: true
zones: [[25500,25500,26500,26500]]

v2.x 新配置：

map_source:
  image: /local/map.png
calibration_source:
  camera: true  # 替代原 camera_calibration
map_modes:
  - template: vacuum_clean_zone_predefined
    predefined_selections:
      - zones: [[25500,25500,26500,26500]]  # 替代原 zones

✓ 验证平台兼容性
确认 vacuum_platform 参数设置正确，例如 Roborock 设备应设置为：

vacuum_platform: roborock

适用场景：从 v1.x 升级到 v2.x 的用户。

性能优化类问题解决方案

如何解决卡片加载缓慢问题

卡片加载超过5秒或操作卡顿，可通过以下优化提升性能：

✓ 优化地图资源
减小地图图片尺寸并裁剪多余区域：

map_source:
  image: /local/map.png
  crop: {top: 50, bottom: 50, left: 30, right: 30}  # 裁剪冗余区域

✓ 精简预定义区域
当 predefined_selections 中定义的区域超过10个时，建议拆分到不同地图模式：

map_modes:
  - template: vacuum_clean_zone_predefined
    name: 常用区域
    predefined_selections: [客厅, 主卧]  # 保留高频使用区域
  - template: vacuum_clean_zone_predefined
    name: 其他区域
    predefined_selections: [厨房, 书房]  # 拆分低频使用区域

适用场景：低性能设备或配置了大量预定义区域的用户。

如何解决移动设备适配问题

在手机等小屏设备上界面错乱，可通过响应式设置优化：

✓ 调整卡片样式
设置合适的高度并启用溢出控制：

style: |
  ha-card {
    height: 500px;  # 根据设备屏幕调整
    overflow: hidden;
  }

✓ 启用触摸优化
配置双指操作支持：

two_finger_pan: true  # 双指拖动地图
map_locked: false     # 允许地图平移缩放

适用场景：移动设备用户或小尺寸显示面板。

问题自查清单

使用以下清单快速定位常见问题：

• [ ] 地图源配置是否正确设置（camera 或 image）
• [ ] 校准点数量是否满足要求（至少3个）
• [ ] 地图模式是否包含所需功能模板
• [ ] vacuum_platform 是否与设备型号匹配
• [ ] 浏览器缓存是否已清除
• [ ] 机器人实体状态是否正常（开发者工具中检查）

社区支持渠道

如果遇到本文未覆盖的问题，可通过以下渠道获取帮助：

• 项目 GitHub Issues：提交详细配置和问题描述
• Home Assistant 社区论坛：在相关板块寻求帮助
• 开发者文档：查阅项目 docs 目录下的详细配置指南

通过系统化排查和针对性优化，大多数使用问题都能得到有效解决。建议定期关注项目更新，以获取最新功能和兼容性改进。