Savedstate

编写可插拔组件，以便在进程死亡时保存 UI 状态，并在进程重新启动时恢复该状态。

最新更新	稳定版	候选版本	Beta 版	Alpha 版
2024 年 11 月 13 日	1.2.1	-	-	1.3.0-alpha05

声明依赖项

要添加对 SavedState 的依赖项，您必须将 Google Maven 存储库添加到您的项目中。阅读Google 的 Maven 存储库以获取更多信息。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项

Groovy

dependencies {
    // Java language implementation
    implementation "androidx.savedstate:savedstate:1.2.1"

    // Kotlin
    implementation "androidx.savedstate:savedstate-ktx:1.2.1"
}

Kotlin

dependencies {
    // Java language implementation
    implementation("androidx.savedstate:savedstate:1.2.1")

    // Kotlin
    implementation("androidx.savedstate:savedstate-ktx:1.2.1")
}

有关依赖项的更多信息，请参阅添加构建依赖项。

反馈

您的反馈有助于使 Jetpack 变得更好。如果您发现新的问题或有改进此库的想法，请告诉我们。在创建新问题之前，请查看此库中现有的问题。您可以通过点击星形按钮为现有问题添加您的投票。

创建新的问题

有关更多信息，请参阅问题跟踪器文档。

版本 1.3

版本 1.3.0-alpha05

2024 年 11 月 13 日

androidx.savedstate:savedstate-*:1.3.0-alpha05 已发布。版本 1.3.0-alpha05 包含这些提交。

KotlinX 序列化支持

SavedState 现在包含 KotlinX 序列化支持。您可以使用 encodeToSavedState 和 decodeFromSavedState 方法将使用 @Serializable 注释的类转换为 SavedState。返回的 SavedState 在 Android 上是常规的 Bundle，并且可以被任何接受 Bundle 的 API 使用。（I6f59f，b/374102924）
```
@Serializable
data class Person(val firstName: String, val lastName: String)

fun main() {
    val person = Person("John", "Doe")
    val encoded: SavedState = encodeToSavedState(person)
    val decoded: Person = decodeFromSavedState(encoded)
}
```
我们还包含了 saved（一个延迟属性委托），以便于将 @Serializable 类存储在 SavedStateRegistryOwner（例如，ComponentActivity、Fragment 等）中，并使这些类在进程死亡和重建期间自动恢复。请注意，saved 委托是延迟的，并且在访问它之前不会调用 init lambda 或将任何内容保存到 SavedStateRegistry 中。（I66739，b/376027806）
```
@Serializable
data class Person(val firstName: String, val lastName: String)

class MyActivity : ComponentActivity() {
    var person by saved { Person("John", "Doe") }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        this.person = Person("Jane", "Doe")
    }
}
```
在 Lifecycle 2.9.0-alpha07 中添加了一个类似的 saved 属性委托，用于 SavedStateHandle。

API 变更

向 SavedState 添加 toMap，允许将任何 SavedState 转换为常规的 Map（浅拷贝）。（I487b9，b/334076622）
SavedState KMP 现在支持数组。（Ic0552，b/334076622）

版本 1.3.0-alpha04

2024 年 10 月 30 日

androidx.savedstate:savedstate-*:1.3.0-alpha04 已发布。版本 1.3.0-alpha04 包含这些提交。

API 变更

SavedState KMP 现在支持 Char。（I9ac2f，b/334076622）
向 SavedState KMP 添加 putNull 和 isNull。（Iea71d，b/334076622）
添加其他 savedState 工厂参数，支持初始 Map<String, Any>（I9b37d，b/334076622）
SavedState KMP 现在支持 contentDeepEquals 比较。（Ia515c，b/334076622）
SavedState KMP 现在支持 Long。（I4c180，b/334076622）

版本 1.3.0-alpha03

2024 年 10 月 16 日

androidx.savedstate:savedstate-*:1.3.0-alpha03 已发布，没有显著变化。版本 1.3.0-alpha03 包含这些提交。

版本 1.3.0-alpha02

2024 年 10 月 2 日

androidx.savedstate:savedstate-*:1.3.0-alpha02 已发布。版本 1.3.0-alpha02 包含这些提交。

Kotlin 多平台

SavedState 模块现在与 KMP 兼容。支持的平台现在包括 Android、iOS、Linux、Mac 和 JVM 桌面环境。（I26305，b/334076622）

新功能

引入 SavedState 不透明类型作为抽象，以提供一种一致的方式在 KMP 中保存和恢复应用程序状态。它包括一个 SavedStateReader 和 SavedStateWriter，用于修改要保存的状态。在 Android 上，SavedState 是 Bundle 的类型别名，确保二进制兼容性并促进现有 API 迁移到通用源集。在其他平台上，SavedState 是 Map<String, Any> 实例。（I18575，b/334076622）

  // Create a new SavedState object using the savedState DSL:
  val savedState = savedState {
    putInt("currentPage", 1)
    putString("filter", "favorites")
  }

  // Read from a SavedState object
  val currentPage = savedState.read { getInt("currentPage") }

  // Edit an existing SavedState object
  savedState.write {
    remove("currentPage")
  }

API 变更

SavedStateRegistry 和 SavedStateRegistryController 现在与 KMP 兼容。（Id7bb8，b/334076622）
SavedState、SavedStateWriter 和 SavedStateReader 现在与 KMP 兼容。（I26305，b/334076622）

版本 1.3.0-alpha01

2024 年 8 月 7 日

androidx.savedstate:savedstate:1.3.0-alpha01 和 androidx.savedstate:savedstate-ktx:1.3.0-alpha01 已发布。版本 1.3.0-alpha01 包含这些提交。

API 变更

Kotlin 扩展 savedstate-ktx 现已移至基本 savedstate 模块。（I1cc18，b/274803094）

注意

将 compileSdk 更新为 35（5dc41be）

版本 1.2.1

2023 年 3 月 22 日

androidx.savedstate:savedstate:1.2.1 和 androidx.savedstate:savedstate-ktx:1.2.1 已发布。版本 1.2.1 包含这些提交。

依赖项更新

SavedState 现在依赖于 Lifecycle 2.6.1。（c1f621）

版本 1.2.0

2022 年 6 月 29 日

androidx.savedstate:savedstate:1.2.0 和 androidx.savedstate:savedstate-ktx:1.2.0 已发布。版本 1.2.0 包含这些提交。

自 1.1.0 以来的重要更改

SavedStateRegistryController 现在允许通过 performAttach() 早期附加 SavedStateRegistry。
您现在可以通过 getSavedStateProvider() 从 SavedStateRegistry 中检索先前注册的 SavedStateProvider。
SavedState 库已重写为 Kotlin。
- 对于 SavedStateRegistryOwner，对于用 Kotlin 编写的那些类来说，这是一个**源代码不兼容的更改** - 您现在必须重写 savedStateRegistry 属性，而不是实现以前的 getSavedStateRegistry() 函数。
- 对于 ViewTreeSavedStateRegistryOwner，对于用 Kotlin 编写的那些类来说，这是一个**源代码不兼容的更改** - 您现在必须直接导入并在 View 上使用 Kotlin 扩展方法 androidx.savedstate.setViewTreeSavedStateRegistryOwner 和 androidx.savedstate.findViewTreeSavedStateRegistryOwner 来设置和查找先前设置的所有者。这将替换 savedstate-ktx API 的 findViewTreeSavedStateRegistryOwner。

行为变更

SavedStateRegistry 不再保存空 Bundle，如果没有任何状态要保存。

版本 1.2.0-rc01

2022 年 5 月 11 日

androidx.savedstate:savedstate:1.2.0-rc01 和 androidx.savedstate:savedstate-ktx:1.2.0-rc01 已发布。版本 1.2.0-rc01 包含这些提交。

文档变更

SavedStateRegistryOwner 的 Kdocs 已更新，以阐明所有者在如何实现接口或何时在 SavedStateRegistryController 上调用方法方面应承担的责任和契约。（Iefc95，b/228887344）

版本 1.2.0-beta01

2022 年 4 月 20 日

androidx.savedstate:savedstate:1.2.0-beta01 和 androidx.savedstate:savedstate-ktx:1.2.0-beta01 已发布。版本 1.2.0-beta01 包含这些提交。

API 变更

SavedStateRegistry 和 ViewTreeSavedStateRegistryOwner 类已重写为 Kotlin。对于 ViewTreeSavedStateRegistryOwner，对于用 Kotlin 编写的那些类来说，这是一个**源代码不兼容的更改** - 您现在必须直接导入并在 View 上使用 Kotlin 扩展方法 androidx.savedstate.setViewTreeSavedStateRegistryOwner 和 androidx.savedstate.findViewTreeSavedStateRegistryOwner 来设置和查找先前设置的所有者。这将替换 savedstate-ktx API 的 findViewTreeSavedStateRegistryOwner。这是二进制兼容的，并且对于用 Java 编程语言编写的实现保持源代码兼容。（b/220191285）

版本 1.2.0-alpha02

2022 年 4 月 6 日

androidx.savedstate:savedstate:1.2.0-alpha02 和 androidx.savedstate:savedstate-ktx:1.2.0-alpha02 已发布。版本 1.2.0-alpha02 包含这些提交。

新功能

您现在可以通过 getSavedStateProvider() 从 SavedStateRegistry 中检索先前注册的 SavedStateProvider。（I7ea47，b/215406268）

API 变更

SavedStateRegistryOwner、SavedStateRegistryController 和 Recreator 类已重写为 Kotlin。对于 SavedStateRegistryOwner，这对于用 Kotlin 编写的类来说是**源代码不兼容的更改** - 您现在必须重写 savedStateRegistry 属性，而不是实现之前的 getSavedStateRegistry() 函数。对于用 Java 编程语言编写的实现，这是二进制兼容且源代码兼容的。（b/220191285）

版本 1.2.0-alpha01

2022 年 1 月 26 日

androidx.savedstate:savedstate:1.2.0-alpha01 和 androidx.savedstate:savedstate-ktx:1.2.0-alpha01 已发布。版本 1.2.0-alpha01 包含这些提交。

新功能

SavedStateRegistryController 现在允许通过 performAttach() 早期附加 SavedStateRegistry。（Ice4bf）

行为变更

SavedStateRegistry 如果没有状态需要保存，则不再保存空 Bundle。（aosp/1896865，b/203457956）

版本 1.1.0

2021 年 2 月 10 日

androidx.savedstate:savedstate:1.1.0 和 androidx.savedstate:savedstate-ktx:1.1.0 已发布。版本 1.1.0 包含这些提交。

自 1.0.0 以来主要更改

ViewTreeSavedStateRegistryOwner API：新的 ViewTreeSavedStateRegistryOwner.get(View) API 允许您在给定 View 实例的情况下检索包含的 SavedStateRegistry。您必须升级到Activity 1.2.0、Fragment 1.3.0 和 AppCompat 1.3.0-alpha01 或更高版本才能正确填充此内容。
savedstate-ktx 工件：已添加新的 savedstate-ktx 工件，其中包含一个用于处理 ViewTreeSavedStateRegistryOwner 的 findViewTreeSavedStateRegistryOwner() Kotlin 扩展。

版本 1.1.0-rc01

2020 年 12 月 16 日

androidx.savedstate:savedstate:1.1.0-rc01 和 androidx.savedstate:savedstate-ktx:1.1.0-rc01 已发布，自 1.1.0-beta01 以来没有更改。版本 1.1.0-rc01 包含这些提交。

版本 1.1.0-beta01

2020 年 10 月 1 日

androidx.savedstate:savedstate:1.1.0-beta01 和 androidx.savedstate:savedstate-ktx:1.1.0-beta01 已发布，自 1.1.0-alpha01 以来没有更改。版本 1.1.0-beta01 包含这些提交。

版本 1.1.0-alpha01

2020 年 5 月 20 日

androidx.savedstate:savedstate:1.1.0-alpha01 和 androidx.savedstate:savedstate-ktx:1.1.0-alpha01 已发布。版本 1.1.0-alpha01 包含这些提交。

新功能

新的 ViewTreeSavedStateRegistryOwner.get(View) API 允许您在给定 View 实例的情况下检索包含的 SavedStateRegistry。您必须升级到 Activity 1.2.0-alpha05、Fragment 1.3.0-alpha05 和 AppCompat 1.3.0-alpha01 才能正确填充此内容。（aosp/1298679）
已添加新的 savedstate-ktx 工件，其中包含一个用于处理 ViewTreeSavedStateRegistryOwner 的 findViewTreeSavedStateRegistryOwner() Kotlin 扩展。（aosp/1299434）

版本 1.0.0

2019 年 9 月 5 日

androidx.savedstate:savedstate:1.0.0 已发布。此版本中包含的提交可以在这里找到此处。

SavedState 1.0.0 的主要功能

androidx.savedstate 已发布稳定版本。这是一组 API，允许开发人员将组件插件到 restore / saveInstanceState 过程中。API 的主要入口点是 SavedStateRegistry，它提供了一种使用 consumeRestoredStateForKey 检索先前保存的状态并注册回调到 registerSavedStateProvider 的方法，以便在系统请求时提供保存的状态。

版本 1.0.0-rc01

2019 年 7 月 2 日

androidx.savedstate:savedstate:1.0.0-rc01 已发布。此版本中包含的提交可以在这里找到此处。

错误修复

修复了不正确的 Proguard 规则（b/132655499）

版本 1.0.0-beta01

2019 年 5 月 7 日

androidx.savedstate:savedstate:1.0.0-beta01 已发布。此版本中包含的提交可以在这里找到此处。

版本 1.0.0-alpha02

2019 年 3 月 13 日

androidx.savedstate:savedstate:1.0.0-alpha02 已发布。androidx.savedstate:savedstate 将工件 androidx.savedstate:savedstate-bundle 和 androidx.savedstate:savedstate-common 合并为一个工件，因为已决定简化 savedstate 基础结构并从 SavedStateRegistry 中删除泛型。因此，不需要单独的模块。

此版本中包含的完整提交列表可以在这里找到此处。

新功能

已添加 SavedStateRegistry.runOnNextRecreaction(Class<? extends AutoRecreated> clazz )。当拥有组件重新启动时，将实例化给定的类，并将运行方法 AutoRecreated.onRecreated。

API 更改

从 SavedStateRegistry<T> 中删除了泛型
已删除 AbstractSavedStateRegistry 和 BundlableSavedStateRegistry，请改用简单的 SavedStateRegistry
BundleSavedStateRegistryOwner 重命名为 SavedStateRegistryOwner

版本 1.0.0-alpha01

2018 年 12 月 17 日

这是 SavedState 的第一个版本。

新功能

androidx.savedstate 是一组新的 Alpha API，允许开发人员将组件插件到 restore / saveInstanceState 过程中。API 的主要入口点是 SavedStateRegistry<T>，它提供了一种通过 consumeRestoredStateForKey 检索先前保存的状态并注册回调到 registerSavedStateProvider 的方法，以便在系统请求时提供保存的状态。