用途:为 Home Assistant 自定义集成添加或修复 options flow,让用户在初次配置后仍可修改集成设置(如扫描间隔、功能开关);同时覆盖 reauth 流程,在凭据过期时无需删除集成即可重新认证。
主要能力与用法:
- OptionsFlow 模板:继承 OptionsFlow 并实现 async_step_init,用户提交后返回 async_create_entry(title="", data=user_input),否则用 async_show_form 返回 vol.Schema 表单;示例用 vol.Optional 与 vol.All(vol.Coerce(int), vol.Range(min=10, max=300)) 约束 scan_interval。
- 绑定方式:在 ConfigFlow 类中以 @staticmethod 与 @callback 定义 async_get_options_flow,返回 OptionsFlow 实例。
- strings.json:在 options.step.init 下提供 title、data 与 data_description 文案。
- Reauth 流程:在 ConfigFlow(非 OptionsFlow)中实现 async_step_reauth 与 async_step_reauth_confirm,校验新凭据,调用 async_set_unique_id 与 _abort_if_unique_id_mismatch(reason="wrong_account"),成功后通过 async_update_reload_and_abort 更新条目;协调器中 API 返回 401 时抛 ConfigEntryAuthFailed 触发。
- 数据区分:entry.data 存连接信息(host、凭据),仅在初始化设置;entry.options 存用户偏好,经 options flow 更新,不应把偏好写入 entry.data。
限制与注意:自 2024.12 起不应在 init 中保存 config_entry,改用自动设置的 self.config_entry,该写法在 2025.12 移除;reauth 示例假定 _async_validate_input、CannotConnect、InvalidAuth 已定义在同一 ConfigFlow 类上。其余平台与收费信息暂未提供。