本頁面由 Cloud Translation API 翻譯而成。

已儲存狀態

編寫可插入的元件，在程序失敗時儲存 UI 狀態，並在程序重新啟動時還原。

最近更新時間	穩定版	候選版	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")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

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 UI 以外的地方使用以 Compose 為基礎的輔助 API。使用 Compose UI 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 (延遲屬性委派)，方便您在 SavedStateRegistryOwner 中儲存 @Serializable 類別 (例如 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")
    }
}

生命週期 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)
將 encodeDefaults 新增至 SavedStateConfiguration，允許自訂是否應編碼具有預設值的屬性。(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 搭配使用，或透過 @Contextual 註解與 @Serializable 類別中的屬性搭配使用。(Ic01d2)
在 SavedStateConfig 上支援 classDiscriminator 和 classDiscriminatorMode。(I69b66、b/395104517)

API 變更

將 SavedStateConfig 參數新增至 saved() 委派 (I39b3a)
將內建序列化器設為單例模式物件 (Ifeee4)
SavedStateConfig 屬性現在為公開，其他模組可以使用這些設定。(Ie5f49、b/378897438)
支援 MutableStateFlowSerializer 和 MutableStateSerializer 的 @Serializer(with = ...) (I90953)
將 contentDeepToString 新增至 SavedStateReader (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，即可搭配 Compose 的 MutableState 使用 SavedState 序列化 API。(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)
在類別中標記相關欄位 @Serializable(with = ParcelableSerializer::class)，即可新增 KSerializer 例項，用於編碼/解碼 Bundle 支援的 Java 和 Android 型別。(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 (延遲屬性委派)，方便您在 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 變更

將 toMap 新增至 SavedState，允許將任何 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 而言，這些類別屬於與原始碼不相容的變更，因此您現在必須覆寫 savedStateRegistry 屬性，而不是導入先前的 getSavedStateRegistry() 函式。
- 對這些使用 Kotlin 程式語言編寫的類別而言，例如 ViewTreeSavedStateRegistryOwner，這是與原始碼不相容的變更，因此您現在必須為 androidx.savedstate.setViewTreeSavedStateRegistryOwner 和 androidx.savedstate.findViewTreeSavedStateRegistryOwner 的 View 直接匯入及使用 Kotlin 擴充功能方法，才能設定及找出先前設定的擁有者。這會取代 findViewTreeSavedStateRegistryOwner 的 savedstate-ktx API。

行為變更

如果無法儲存任何狀態，「SavedStateRegistry」就不會再儲存空白的軟體包。

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 類別。對這些使用 Kotlin 程式語言編寫的類別而言，例如 ViewTreeSavedStateRegistryOwner，這是與原始碼不相容的變更，因此您現在必須為 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 而言，這些類別屬於與原始碼不相容的變更，因此您現在必須覆寫 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」就不會再儲存空白的軟體包。(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 可讓您依據 SavedStateRegistry 執行個體，擷取其所屬的 View。您必須升級至 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 可讓開發人員將元件附加至還原 / 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，可讓開發人員將元件附加至還原 / saveInstanceState 程序。API 的主要進入點是 SavedStateRegistry<T>，可讓您透過 consumeRestoredStateForKey 擷取先前儲存的狀態，並向 registerSavedStateProvider 註冊回呼，以在系統要求時提供已儲存的狀態。