用途:面向 Home Assistant 轮询式集成,提供 DataUpdateCoordinator 的实现或修复模板,集中数据抓取、向实体分发更新,并处理错误与重试。
主要能力:给出 2025 版完整协调器模板,含 _async_setup 一次性初始化(HA 2024.8+)、_async_update_data 周期抓取、错误处理参考(UpdateFailed、ConfigEntryAuthFailed、ConfigEntryError)、always_update、retry_after(HA 2025.11+)、重触发(HA 2025.10+),以及在 init.py、实体平台、动态设备发现中的用法,并列常见错误。
使用方式:在配置项中实例化协调器:coordinator = {Name}Coordinator(hass, entry),调用 await coordinator.async_config_entry_first_refresh() 触发 _async_setup 与 _async_update_data,再用 entry.runtime_data 保存并转发平台;实体继承 CoordinatorEntity 订阅更新。
限制与提示:always_update=False 仅当返回数据具备基于值的 eq(普通 dict/dataclass)时才安全;_async_update_data 中不得阻塞 I/O,应使用 await hass.async_add_executor_job();避免过宽捕获异常,应让 ConfigEntryAuthFailed 正常传播;用 entry.runtime_data 而非 hass.data。具体集成细节需按各集成资料确定,本资料未提供平台版本兼容范围之外的安装命令与价格信息。