已儲存狀態
最近更新時間 | 穩定版 | 候選版 | 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 UI1.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 序列化支援
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 變更
- 將
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
現在依附於 Lifecycle2.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()
函式。 - 對這些使用 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 版本
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
執行個體。您必須升級為Activity1.2.0
、Fragment1.3.0
,以及AppCompat1.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
。您必須升級至 Activity1.2.0-alpha05
、Fragment1.3.0-alpha05
和 AppCompat1.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
註冊回呼,以在系統要求時提供已儲存的狀態。