此页面由 Cloud Translation API 翻译。

Savedstate

编写可插入组件，以在进程终止时保存界面状态，并在进程重启时恢复界面状态。

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2025 年 7 月 2 日	1.3.1	-	-	-

声明依赖项

如需添加 SavedState 的依赖项，您必须将 Google Maven 仓库添加到项目中。如需了解详情，请参阅 Google 的 Maven 仓库。

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

Groovy

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

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

Kotlin

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

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

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 1.3

版本 1.3.0

2025 年 5 月 7 日

发布了 androidx.savedstate:savedstate-*:1.3.0。版本 1.3.0 中包含这些提交内容。

自 1.2.0 以来的重要变更

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

Kotlin Multiplatform

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

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

我们还添加了 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 中包含这些提交内容。

新功能

添加了用于序列化 kotlinx.coroutines.flow.MutableStateFlow 的 MutableStateFlowSerializer。（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 实例，这些实例可用于对 Bundle 支持的 Java 和 Android 类型进行编码/解码，只需使用 @Serializable(with = ParcelableSerializer::class) 标记类中的相关字段即可。（I8c10f、I28caf、b/376026712）
现在，可以通过视图的不相交父级（例如 ViewOverlay）解析通过 findViewTreeSavedStateRegistryOwner 检索到的 SavedStateRegistryOwner 实例。如需详细了解不相交的视图父级，请参阅核心版本说明或 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 序列化支持

@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）
将 putNull 和 isNull 添加到 SavedState KMP。（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 Multiplatform

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

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。
用 Kotlin 重写了 SavedState 库。
- 就SavedStateRegistryOwner而言，对于用 Kotlin 编写的类，这项变更与源代码不兼容。现在，您必须替换 savedStateRegistry 属性，而不是实现之前的 getSavedStateRegistry() 函数。
- 就ViewTreeSavedStateRegistryOwner而言，对于用 Kotlin 编写的类，这项变更与源代码不兼容。现在，您必须直接在 androidx.savedstate.setViewTreeSavedStateRegistryOwner 和 androidx.savedstate.findViewTreeSavedStateRegistryOwner 的 View 上导入并使用 Kotlin 扩展方法，才能设置和查找之前设置的所有者。这取代了 findViewTreeSavedStateRegistryOwner 的 savedstate-ktx 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 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 变更

使用 Kotlin 重写了 SavedStateRegistry 和 ViewTreeSavedStateRegistryOwner 类。就ViewTreeSavedStateRegistryOwner而言，对于用 Kotlin 编写的类，这项变更与源代码不兼容。现在，您必须直接在 androidx.savedstate.setViewTreeSavedStateRegistryOwner 和 androidx.savedstate.findViewTreeSavedStateRegistryOwner 的 View 上导入并使用 Kotlin 扩展方法，才能设置和查找之前设置的所有者。这取代了 findViewTreeSavedStateRegistryOwner 的 savedstate-ktx 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 变更

使用 Kotlin 重写了 SavedStateRegistryOwner、SavedStateRegistryController 和 Recreator 类。就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 或更高版本，才能正确填充 (populate) 此 API。
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，才能正确填充 (populate) 此 API。(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 允许开发者将组件以插件形式添加到恢复 /saveInstanceState 进程。该 API 的主要入口点是 SavedStateRegistry，它提供了一种方法来使用 consumeRestoredStateForKey检索之前保存的状态，并注册一个回调，通过调用 registerSavedStateProvider 在系统请求时提供已保存的状态。

版本 1.0.0-rc01

2019 年 7 月 2 日

发布了 androidx.savedstate:savedstate:1.0.0-rc01。点击此处可查看此版本中包含的提交内容。

bug 修复

修复了不正确的 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，允许开发者将组件以插件形式添加到恢复 /saveInstanceState 进程。该 API 的主要入口点是 SavedStateRegistry<T>，它提供了一种方法来通过 consumeRestoredStateForKey 检索之前保存的状态，并注册一个 registerSavedStateProvider 回调，以便在系统请求时提供已保存的状态。