已儲存狀態

編寫可插入的元件,在程序失敗時儲存 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 中提供一致的方式來儲存及還原應用程式狀態。當中包含 SavedStateReaderSavedStateWriter,可修改要儲存的狀態。在 Android 中,SavedStateBundle 的型別別名,可確保二進位檔相容性,並簡化現有 API 遷移至通用來源集的程序。在其他平台上,SavedStateMap<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 序列化。您可以使用 encodeToSavedStatedecodeFromSavedState 方法,將以 @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 類別 (例如 ComponentActivityFragment 等),並在程序終止和重新建立時自動還原這些類別。請注意,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 集合新增非具體化方法變體。(I0b641b/399820614)
  • encodeDefaults 新增至 SavedStateConfiguration,允許自訂是否應編碼具有預設值的屬性。(I893ccb/395104517)
  • 新增 SnapshotStateMapSerializer,支援 mutableStateMapOf。(Ie6f19b/378895074)
  • 新增 SnapshotStateListSerializer,支援 mutableStateListOf。(I4d888b/378895074)
  • SavedStateReader.get 變數新增 getOrNull 替代方法。這些方法會自動將原始值裝箱。(I6228cb/399820614)

API 變更

  • SavedStateReader 移除 getOrElse,改用 getOrNull() ?: else()。(I87317b/399820614)
  • SavedStateReaderSavedStateWriter 方法中移除 inline 修飾符。(If2a02b/399820614)
  • 從公用 API 中移除 Android 專屬的內建 List 和 Array 序列化程式 (Ida293)
  • SparseParcelableArraySerializer 替換成 SparseArraySerializer (I91de8)
  • 讓所有 SavedStateReader.get 的行為保持一致,在值類型與傳回類型不符時擲回例外狀況 (I78c4ab/399317598)
  • SavedState*Delegates 重新命名為 SavedState*Delegate。(I8589bb/399629301)
  • SavedStateConfig 重新命名為 SavedStateConfiguration。(I043a5b/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 上支援 classDiscriminatorclassDiscriminatorMode。(I69b66b/395104517)

API 變更

  • SavedStateConfig 參數新增至 saved() 委派 (I39b3a)
  • 將內建序列化器設為單例模式物件 (Ifeee4)
  • SavedStateConfig 屬性現在為公開,其他模組可以使用這些設定。(Ie5f49b/378897438)
  • 支援 MutableStateFlowSerializerMutableStateSerializer@Serializer(with = ...) (I90953)
  • contentDeepToString 新增至 SavedStateReader (I14d10)

1.3.0-alpha08 版

2025 年 2 月 12 日

發布 androidx.savedstate:savedstate-*:1.3.0-alpha08。1.3.0-alpha08 版包含這些修訂項目

新功能

  • MutableStateSerializerlifecycle-viewmodel-compose 移至 savedstate-compose,即可搭配 Compose 的 MutableState 使用 SavedState 序列化 API。(I4f690b/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。(I6a892b/378895070)

API 變更

  • 以預設參數取代過載的 SavedStateRegistryOwner.saved() 委派函式 (Icd1c1)
  • JavaSerializableSerializerParcelableSerializer 設為抽象 (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 現在支援:IBinderSizeSizeFArray<Parcelable>SparseArray<Parcelable> 和 Serializable (Android)。(I1ba94b/334076622)
  • 在類別中標記相關欄位 @Serializable(with = ParcelableSerializer::class),即可新增 KSerializer 例項,用於編碼/解碼 Bundle 支援的 Java 和 Android 型別。(I8c10fI28cafb/376026712)
  • 現在可以透過檢視畫面的不相交父項 (例如 ViewOverlay) 解析透過 findViewTreeSavedStateRegistryOwner 擷取的 SavedStateRegistryOwner 執行個體。如要進一步瞭解不連續檢視區塊父項,請參閱核心版本的版本資訊或 ViewTree.setViewTreeDisjointParent 中的說明文件。(Iccb33)

API 變更

  • 讓命名和套件組織與 SavedStateRegistryOwnerDelegate 更一致 (I8c135b/376026744)

1.3.0-alpha05 版

2024 年 11 月 13 日

發布 androidx.savedstate:savedstate-*:1.3.0-alpha05。1.3.0-alpha05 版包含這些修訂項目

KotlinX 序列化支援

  • SavedState 現在支援 KotlinX 序列化。您可以使用 encodeToSavedStatedecodeFromSavedState 方法,將以 @Serializable 註解的類別轉換為 SavedState。傳回的 SavedState 是 Android 上的標準 Bundle,可供接受 Bundle 的任何 API 使用。(I6f59fb/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 類別 (例如 ComponentActivityFragment 等),並在程序終止和重新建立時自動還原這些類別。請注意,saved 委派項是延遲的,在存取前不會呼叫 init lambda,也不會將任何內容儲存至 SavedStateRegistry。(I66739b/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 (淺層副本)。(I487b9b/334076622)
  • SavedState KMP 現在支援陣列。(Ic0552b/334076622)

1.3.0-alpha04 版本

2024 年 10 月 30 日

發布 androidx.savedstate:savedstate-*:1.3.0-alpha04。1.3.0-alpha04 版包含這些修訂項目

API 變更

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 電腦環境。(I26305b/334076622)

新功能

  • 導入 SavedState 不透明型別做為抽象概念,在 KMP 中提供一致的方式來儲存及還原應用程式狀態。當中包含 SavedStateReaderSavedStateWriter,可修改要儲存的狀態。在 Android 中,SavedStateBundle 的型別別名,可確保二進位檔相容性,並簡化現有 API 遷移至通用來源集的程序。在其他平台上,SavedStateMap<String, Any> 例項。(I18575b/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 變更

  • SavedStateRegistrySavedStateRegistryController 現在與 KMP 相容。(Id7bb8b/334076622)
  • SavedStateSavedStateWriterSavedStateReader 現在與 KMP 相容。(I26305b/334076622)

1.3.0-alpha01 版本

2024 年 8 月 7 日

發布 androidx.savedstate:savedstate:1.3.0-alpha01androidx.savedstate:savedstate-ktx:1.3.0-alpha01。1.3.0-alpha01 版包含這些修訂項目

API 變更

  • savedstate-ktx Kotlin 擴充功能現已移至基礎 savedstate 模組。(I1cc18b/274803094)

附註

  • compileSdk 更新至 35 (5dc41be)

1.2.1 版本

1.2.1 版本

2023 年 3 月 22 日

發布 androidx.savedstate:savedstate:1.2.1androidx.savedstate:savedstate-ktx:1.2.11.2.1 版本包含以下修訂項目。

依附元件更新

1.2.0 版本

1.2.0 版本

2022 年 6 月 29 日

發布 androidx.savedstate:savedstate:1.2.0androidx.savedstate:savedstate-ktx:1.2.01.2.0 版本包含以下修訂項目。

自 1.1.0 版以來的重要異動

  • SavedStateRegistryController 現在允許透過 performAttach() 提前附加 SavedStateRegistry
  • 您現在可以透過 getSavedStateProvider()SavedStateRegistry 擷取先前註冊的 SavedStateProvider
  • 已改寫 Kotlin 內的 SavedState 程式庫。
    • SavedStateRegistryOwner 而言,這些類別屬於與原始碼不相容的變更,因此您現在必須覆寫 savedStateRegistry 屬性,而不是導入先前的 getSavedStateRegistry() 函式。
    • 對這些使用 Kotlin 程式語言編寫的類別而言,例如 ViewTreeSavedStateRegistryOwner,這是與原始碼不相容的變更,因此您現在必須為 androidx.savedstate.setViewTreeSavedStateRegistryOwnerandroidx.savedstate.findViewTreeSavedStateRegistryOwnerView 直接匯入及使用 Kotlin 擴充功能方法,才能設定及找出先前設定的擁有者。這會取代 findViewTreeSavedStateRegistryOwnersavedstate-ktx API。

行為變更

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

1.2.0-rc01 版本

2022 年 5 月 11 日

發布 androidx.savedstate:savedstate:1.2.0-rc01androidx.savedstate:savedstate-ktx:1.2.0-rc011.2.0-rc01 版包含此連結所列的修訂項目。

說明文件變更

  • SavedStateRegistryOwner Kdocs》已更新,明確指出擁有者在應如何實作介面,或何時可透過 SavedStateRegistryController 呼叫方法時應承擔的責任以及受到的約束 (Iefc95b/228887344)。

1.2.0-beta01 版本

2022 年 4 月 20 日

發布 androidx.savedstate:savedstate:1.2.0-beta01androidx.savedstate:savedstate-ktx:1.2.0-beta011.2.0-beta01 版包含此連結所列的修訂項目。

API 變更

  • 我們已使用 Kotlin 程式語言重新編寫 SavedStateRegistryViewTreeSavedStateRegistryOwner 類別。對這些使用 Kotlin 程式語言編寫的類別而言,例如 ViewTreeSavedStateRegistryOwner,這是與原始碼不相容的變更,因此您現在必須為 androidx.savedstate.setViewTreeSavedStateRegistryOwnerandroidx.savedstate.findViewTreeSavedStateRegistryOwnerView 直接匯入及使用 Kotlin 擴充功能方法,才能設定及找出先前設定的擁有者。這會取代 findViewTreeSavedStateRegistryOwnersavedstate-ktx API,另外,這與二進位檔相容,而且以 Java 程式設計語言編寫的實作仍保持原始碼相容性 (b/220191285)

1.2.0-alpha02 版本

2022 年 4 月 6 日

發布 androidx.savedstate:savedstate:1.2.0-alpha02androidx.savedstate:savedstate-ktx:1.2.0-alpha021.2.0-alpha02 版包含此連結所列的修訂項目。

新功能

  • 您現在可以透過 getSavedStateProvider()SavedStateRegistry 擷取先前註冊的 SavedStateProvider (I7ea47b/215406268)

API 變更

  • 我們已使用 Kotlin 程式語言重新編寫 SavedStateRegistryOwnerSavedStateRegistryControllerRecreator 類別。對 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/1896865b/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.0Fragment 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-rc01androidx.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-beta01androidx.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 版本包含這些修訂版本。

新功能

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。您可以前往這裡查看這個版本包含的修訂項目。

修正錯誤

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-alpha02androidx.savedstate:savedstate 將成果 androidx.savedstate:savedstate-bundleandroidx.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 註冊回呼,以在系統要求時提供已儲存的狀態。