此页面由 Cloud Translation API 翻译。

Savedstate

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

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2024 年 12 月 11 日	1.2.1	-	-	1.3.0-alpha06

声明依赖项

如需添加 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")
}

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

反馈

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

创建新问题

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

版本 1.3

版本 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）
通过使用 @Serializable(with = ParcelableSerializer::class) 标记类中的相关字段，添加可用于编码/解码 Bundle 支持的 Java 和 Android 类型的 KSerializer 实例。（I8c10f、I28caf、b/376026712）
现在，可以通过视图的互不相交的父级（例如 ViewOverlay）解析通过 findViewTreeSavedStateRegistryOwner 检索的 SavedStateRegistryOwner 实例。如需详细了解不相交的 View 父级，请参阅核心组件的版本说明或 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（一个延迟属性委托），以便轻松地在 SavedStateRegistryOwner 中存储 @Serializable 类（例如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")
    }
}

生命周期 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）
添加了支持初始 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 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 回调，以便在系统请求时提供已保存的状态。