Savedstate

声明依赖项

要添加 SavedState 的依赖项，您必须将 Google Maven 仓库添加到您的项目中。如需了解更多信息，请阅读Google 的 Maven 仓库。

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

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

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

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

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

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

反馈

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

创建新问题

如需了解更多信息，请参阅问题跟踪器文档。

版本 1.3

版本 1.3.0

2025 年 5 月 7 日

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

自 1.2.0 版以来的重要变更

• LocalSavedStateRegistryOwner 已从 Compose UI 移至新的 savedstate-compose 模块，以便其基于 Compose 的辅助 API 可以在 Compose UI 之外使用。在使用 Compose UI 1.9.0-alpha02 及更高版本时应始终使用此模块，但它向后兼容，因此可以与所有 Compose 版本一起使用。
• savedstate-ktx Kotlin 扩展现在已移至基础 savedstate 模块。
• 通过 findViewTreeSavedStateRegistryOwner 检索到的 SavedStateRegistryOwner 实例现在可以通过视图的不相交父级（例如 ViewOverlay）进行解析。如需了解有关不相交视图父级的更多信息，请参阅核心版本说明或 ViewTree.setViewTreeDisjointParent 中的文档。

Kotlin 多平台

• SavedState 模块现在与 KMP 兼容。支持的平台现在包括 Android、iOS、Linux、Mac 和 JVM 桌面环境。

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

    // 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")
    }
  

KotlinX 序列化支持

• SavedState 现在包含 KotlinX 序列化支持。您可以使用 encodeToSavedState 和 decodeFromSavedState 方法将带有 @Serializable 注解的类转换为 SavedState。返回的 SavedState 在 Android 上是一个常规的 Bundle，可以被接受 Bundle 的任何 API 使用。

  @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)
  }
  

• 虽然大多数类型（例如基本类型）无需任何配置即可直接支持，但可与 @Serializable(with = ___:class) 一起使用的其他序列化器可在 savedstate 模块中的 androidx.savedstate.serialization.serializers 软件包和 savedstate-compose 模块中的 androidx.savedstate.compose.serialization.serializers 软件包中找到。

• 我们还包含了 saved（一个惰性属性委托），以便轻松地将 @Serializable 类存储在 SavedStateRegistryOwner 中（例如 ComponentActivity、Fragment 等），并使这些类在进程终止和重新创建后自动恢复。请注意，saved 委托是惰性的，在访问之前不会调用 init lambda 或将任何内容保存到 SavedStateRegistry 中。

  @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 中，还为 SavedStateHandle 添加了类似的 saved 属性委托。

版本 1.3.0-rc01

2025 年 4 月 23 日

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

版本 1.3.0-beta01

2025 年 4 月 9 日

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

依赖项更新

• 此库现在面向 Kotlin 2.0 语言级别，并要求 KGP 2.0.0 或更高版本。（Idb6b5）

版本 1.3.0-alpha11

2025 年 3 月 26 日

androidx.savedstate:savedstate-*:1.3.0-alpha11 已发布，无显著公共变更。版本 1.3.0-alpha11 包含这些提交。

版本 1.3.0-alpha10

2025 年 3 月 12 日

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

新功能

• 为 SavedStateReader 中的 get 集合添加非具体化方法变体。（I0b641，b/399820614）
• 为 SavedStateConfiguration 添加 encodeDefaults，允许自定义是否应编码具有默认值的属性。（I893cc，b/395104517）
• 添加 SnapshotStateMapSerializer 以支持 mutableStateMapOf。（Ie6f19，b/378895074）
• 添加 SnapshotStateListSerializer 以支持 mutableStateListOf。（I4d888，b/378895074）
• 为 SavedStateReader.get 变体添加 getOrNull 替代方法。这些方法将自动装箱基本类型值。（I6228c，b/399820614）

API 变更

• 从 SavedStateReader 中移除 getOrElse，转而使用 getOrNull() ?: else()。（I87317，b/399820614）
• 从 SavedStateReader 和 SavedStateWriter 方法中移除 inline 修饰符。（If2a02，b/399820614）
• 从公共 API 中移除内置的 Android 特定 List 和 Array 序列化器（Ida293）
• 将 SparseParcelableArraySerializer 替换为 SparseArraySerializer（I91de8）
• 通过在值类型与返回类型不匹配时抛出异常，使所有 SavedStateReader.get 行为一致（I78c4a，b/399317598）
• 将 SavedState*Delegates 重命名为 SavedState*Delegate。（I8589b，b/399629301）
• 将 SavedStateConfig 重命名为 SavedStateConfiguration。（I043a5，b/399629301）

版本 1.3.0-alpha09

2025 年 2 月 26 日

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

新功能

• 为内置类型添加回退，确保 Bundle 支持的所有类型默认情况下都可以与 encodeAsSavedState/decodeFromSavedState 一起使用，或者对于 @Serializable 类中的属性，可以通过 @Contextual 注解使用。（Ic01d2）
• 在 SavedStateConfig 上包含对 classDiscriminator 和 classDiscriminatorMode 的支持。（I69b66，b/395104517）

API 变更

• 向 saved() 委托添加 SavedStateConfig 参数（I39b3a）
• 使内置序列化器成为单例对象（Ifeee4）
• SavedStateConfig 属性现在是公共的，允许其他模块使用这些配置。（Ie5f49，b/378897438）
• 支持 MutableStateFlowSerializer 和 MutableStateSerializer 的 @Serializer(with = ...)（I90953）
• 向 SavedStateReader 添加 contentDeepToString（I14d10）

版本 1.3.0-alpha08

2025 年 2 月 12 日

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

新功能

• 将 MutableStateSerializer 从 lifecycle-viewmodel-compose 移至 savedstate-compose，允许您将 SavedState 序列化 API 与 Compose 的 MutableState 一起使用。（I4f690，b/378895074）

API 变更

• 添加一个工厂函数，用于从现有 SavedState 创建 SavedState。（I39f9a）
• 在 androidx.savedstate 中添加对 Array<SavedState> 和 List<SavedState> 的支持。（Idd8a5）
• 为 SavedState 编码/解码添加 SavedStateConfig 可选参数（I6c4c0）

版本 1.3.0-alpha07

2025 年 1 月 29 日

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

新功能

• 添加 MutableStateFlowSerializer 用于序列化 kotlinx.coroutines.flow.MutableStateFlow。（I6a892，b/378895070）

API 变更

• 将重载的 SavedStateRegistryOwner.saved() 委托函数替换为默认参数（Icd1c1）
• 使 JavaSerializableSerializer 和 ParcelableSerializer 成为抽象类（I268f6）
• 从 CharSequenceSerializer 中移除泛型 T : CharSequence（Ib40bd）

版本 1.3.0-alpha06

2024 年 12 月 11 日

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

新功能

• SavedState KMP 现在支持：IBinder、Size、SizeF、Array<Parcelable>、SparseArray<Parcelable> 和 Serializable (Android)。（I1ba94，b/334076622）
• 添加 KSerializer 实例，通过在您的类中用 @Serializable(with = ParcelableSerializer::class) 标记相关字段，这些实例可用于编码/解码 Bundle 支持的 Java 和 Android 类型。（I8c10f，I28caf，b/376026712）
• 通过 findViewTreeSavedStateRegistryOwner 检索到的 SavedStateRegistryOwner 实例现在可以通过视图的不相交父级（例如 ViewOverlay）进行解析。如需了解有关不相交视图父级的更多信息，请参阅核心版本说明或 ViewTree.setViewTreeDisjointParent 中的文档。（Iccb33）

API 变更

• 使命名和包组织与 SavedStateRegistryOwnerDelegate 更加一致（I8c135，b/376026744）

版本 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 中，还为 SavedStateHandle 添加了类似的 saved 属性委托。

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）
• 添加支持初始 Map<String, Any> 的额外 savedState 工厂参数（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 变更

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

注意

• 将 compileSdk 更新到 35（5dc41be）

版本 1.2.1

版本 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

版本 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 的 findViewTreeSavedStateRegistryOwner API。

行为变更

• 如果没有任何状态可保存，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 Kdoc 已更新，以阐明所有者在如何实现接口或何时调用 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 的 findViewTreeSavedStateRegistryOwner API。对于用 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

版本 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

版本 1.0.0

2019 年 9 月 5 日

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

SavedState 1.0.0 的主要功能

androidx.savedstate 已升级为稳定版。这是一组 API，允许开发者将组件插入到恢复/保存实例状态的过程中。该 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，允许开发者将组件插入到恢复/保存实例状态的过程中。该 API 的主要入口点是 SavedStateRegistry<T>，它提供了一种通过 consumeRestoredStateForKey 检索先前保存状态的方法，并注册一个回调到 registerSavedStateProvider，以便在系统请求时提供保存状态。