已儲存狀態

宣告依附元件

如要新增 SavedState 的依附元件，您必須在專案中新增 Google Maven 存放區。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

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

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

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

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

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

意見回饋

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

建立新問題

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

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 之前，不會呼叫 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 版本

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。
• 已改寫 Kotlin 內的 SavedState 程式庫。
  • 對 SavedStateRegistryOwner 而言，這些類別屬於與原始碼不相容的變更，因此您現在必須覆寫 savedStateRegistry 屬性，而不是導入先前的 getSavedStateRegistry() 函式。
  • 對 ViewTreeSavedStateRegistryOwner 而言，這些類別屬於與原始碼不相容的變更，因此您現在必須直接匯入並使用 Kotlin 擴充功能方法，才能設定及找出先前設定的擁有者。Viewandroidx.savedstate.setViewTreeSavedStateRegistryOwnerandroidx.savedstate.findViewTreeSavedStateRegistryOwner這會取代 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 類別。對 ViewTreeSavedStateRegistryOwner 而言，這些類別屬於與原始碼不相容的變更，因此您現在必須直接匯入並使用 Kotlin 擴充功能方法，才能設定及找出先前設定的擁有者。Viewandroidx.savedstate.setViewTreeSavedStateRegistryOwnerandroidx.savedstate.findViewTreeSavedStateRegistryOwner這會取代 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 版本

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 註冊回呼，以在系統要求時提供已儲存的狀態。