SavedStateRegistry：宿主恢复协议

一条完整链路

宿主实现 SavedStateRegistryOwner。组件用唯一 key 注册 SavedStateProvider；保存阶段 registry 调用 provider；重建后组件用同一 key 消费恢复结果。

private const val KEY = "search-state"

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val restored = savedStateRegistry.consumeRestoredStateForKey(KEY)
    query = restored?.read { getStringOrNull("query") }.orEmpty()

    savedStateRegistry.registerSavedStateProvider(KEY) {
        savedState { putString("query", query) }
    }
}

provider 是延迟执行的：注册时不用立即构造状态，系统请求保存时才读取最新值。

为什么只能消费一次

consumeRestoredStateForKey 的语义是取走该 key 的恢复状态，避免多个组件把同一份状态都当成自己的。key 必须稳定且在同一 registry 内唯一。

自定义宿主

自定义 SavedStateRegistryOwner 需要通过 SavedStateRegistryController 按顺序调用 performAttach、performRestore 和 performSave，并正确提供 Lifecycle。Activity/Fragment 已完成这些连接，业务代码通常不应自己控制 controller。

新的序列化 delegate

当前源码支持对 SavedStateRegistryOwner 使用 saved delegate，并通过 kotlinx.serialization 保存对象：

复制即用

@Serializable
data class User(val id: Int, val name: String)

val user by saved(key = "profile") { User(0, "") }

这是当前 alpha 源码能力；采用前应确认项目实际依赖版本。

常见陷阱

key 冲突：同一 registry 内 key 必须唯一，前缀组件名。
consume 两次：consumeRestoredStateForKey 只消费一次，第二个组件取不到。
provider 里放重活：保存阶段在主线程执行，别做耗时操作。
自己控制 controller：Activity/Fragment 已完成连接，业务代码不要调用。

要点

一条完整链路：宿主实现 SavedStateRegistryOwner。组件用唯一 key 注册 SavedStateProvider；保存阶段 registry 调用 provider；重建后组件用同一 key 消费恢复结果。
为什么只能消费一次：consumeRestoredStateForKey 的语义是取走该 key 的恢复状态，避免多个组件把同一份状态都当成自己的。key 必须稳定且在同一 registry 内唯一。
自定义宿主：自定义 SavedStateRegistryOwner 需要通过 SavedStateRegistryController 按顺序调用 performAttach、performRestore 和 performSave…
新的序列化 delegate：当前源码支持对 SavedStateRegistryOwner 使用 saved delegate，并通过 kotlinx.serialization 保存对象：

SavedStateRegistry：宿主恢复协议1.6.0-alpha01