生命週期
下表列出了 androidx.lifecycle
群組中的所有構件。
構件 | 穩定版 | 候選版 | Beta 版 | Alpha 版 |
---|---|---|---|---|
lifecycle-* | 2.8.4 版 | - | - | 2.9.0-alpha01 版 |
lifecycle-viewmodel-compose | 2.8.4 版 | - | - | 2.9.0-alpha01 版 |
宣告依附元件
如果要為 Lifecycle 新增依附元件,您必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。
在應用程式或模組的 build.gradle
檔案中,新增您需要的構件依附元件:
Kotlin
Groovy
dependencies { def lifecycle_version = "2.8.4" def arch_version = "2.2.0" // ViewModel implementation "androidx.lifecycle:lifecycle-viewmodel-ktx:$lifecycle_version" // ViewModel utilities for Compose implementation "androidx.lifecycle:lifecycle-viewmodel-compose:$lifecycle_version" // LiveData implementation "androidx.lifecycle:lifecycle-livedata-ktx:$lifecycle_version" // Lifecycles only (without ViewModel or LiveData) implementation "androidx.lifecycle:lifecycle-runtime-ktx:$lifecycle_version" // Lifecycle utilities for Compose implementation "androidx.lifecycle:lifecycle-runtime-compose:$lifecycle_version" // Saved state module for ViewModel implementation "androidx.lifecycle:lifecycle-viewmodel-savedstate:$lifecycle_version" // Annotation processor kapt "androidx.lifecycle:lifecycle-compiler:$lifecycle_version" // alternately - if using Java8, use the following instead of lifecycle-compiler implementation "androidx.lifecycle:lifecycle-common-java8:$lifecycle_version" // optional - helpers for implementing LifecycleOwner in a Service implementation "androidx.lifecycle:lifecycle-service:$lifecycle_version" // optional - ProcessLifecycleOwner provides a lifecycle for the whole application process implementation "androidx.lifecycle:lifecycle-process:$lifecycle_version" // optional - ReactiveStreams support for LiveData implementation "androidx.lifecycle:lifecycle-reactivestreams-ktx:$lifecycle_version" // optional - Test helpers for LiveData testImplementation "androidx.arch.core:core-testing:$arch_version" // optional - Test helpers for Lifecycle runtime testImplementation "androidx.lifecycle:lifecycle-runtime-testing:$lifecycle_version" }
Kotlin
dependencies { val lifecycle_version = "2.8.4" val arch_version = "2.2.0" // ViewModel implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:$lifecycle_version") // ViewModel utilities for Compose implementation("androidx.lifecycle:lifecycle-viewmodel-compose:$lifecycle_version") // LiveData implementation("androidx.lifecycle:lifecycle-livedata-ktx:$lifecycle_version") // Lifecycles only (without ViewModel or LiveData) implementation("androidx.lifecycle:lifecycle-runtime-ktx:$lifecycle_version") // Lifecycle utilities for Compose implementation("androidx.lifecycle:lifecycle-runtime-compose:$lifecycle_version") // Saved state module for ViewModel implementation("androidx.lifecycle:lifecycle-viewmodel-savedstate:$lifecycle_version") // Annotation processor kapt("androidx.lifecycle:lifecycle-compiler:$lifecycle_version") // alternately - if using Java8, use the following instead of lifecycle-compiler implementation("androidx.lifecycle:lifecycle-common-java8:$lifecycle_version") // optional - helpers for implementing LifecycleOwner in a Service implementation("androidx.lifecycle:lifecycle-service:$lifecycle_version") // optional - ProcessLifecycleOwner provides a lifecycle for the whole application process implementation("androidx.lifecycle:lifecycle-process:$lifecycle_version") // optional - ReactiveStreams support for LiveData implementation("androidx.lifecycle:lifecycle-reactivestreams-ktx:$lifecycle_version") // optional - Test helpers for LiveData testImplementation("androidx.arch.core:core-testing:$arch_version") // optional - Test helpers for Lifecycle runtime testImplementation ("androidx.lifecycle:lifecycle-runtime-testing:$lifecycle_version") }
Java
Groovy
dependencies { def lifecycle_version = "2.8.4" def arch_version = "2.2.0" // ViewModel implementation "androidx.lifecycle:lifecycle-viewmodel:$lifecycle_version" // LiveData implementation "androidx.lifecycle:lifecycle-livedata:$lifecycle_version" // Lifecycles only (without ViewModel or LiveData) implementation "androidx.lifecycle:lifecycle-runtime:$lifecycle_version" // Saved state module for ViewModel implementation "androidx.lifecycle:lifecycle-viewmodel-savedstate:$lifecycle_version" // Annotation processor annotationProcessor "androidx.lifecycle:lifecycle-compiler:$lifecycle_version" // alternately - if using Java8, use the following instead of lifecycle-compiler implementation "androidx.lifecycle:lifecycle-common-java8:$lifecycle_version" // optional - helpers for implementing LifecycleOwner in a Service implementation "androidx.lifecycle:lifecycle-service:$lifecycle_version" // optional - ProcessLifecycleOwner provides a lifecycle for the whole application process implementation "androidx.lifecycle:lifecycle-process:$lifecycle_version" // optional - ReactiveStreams support for LiveData implementation "androidx.lifecycle:lifecycle-reactivestreams:$lifecycle_version" // optional - Test helpers for LiveData testImplementation "androidx.arch.core:core-testing:$arch_version" // optional - Test helpers for Lifecycle runtime testImplementation "androidx.lifecycle:lifecycle-runtime-testing:$lifecycle_version" }
Kotlin
dependencies { val lifecycle_version = "2.8.4" val arch_version = "2.2.0" // ViewModel implementation("androidx.lifecycle:lifecycle-viewmodel:$lifecycle_version") // LiveData implementation("androidx.lifecycle:lifecycle-livedata:$lifecycle_version") // Lifecycles only (without ViewModel or LiveData) implementation("androidx.lifecycle:lifecycle-runtime:$lifecycle_version") // Saved state module for ViewModel implementation("androidx.lifecycle:lifecycle-viewmodel-savedstate:$lifecycle_version") // Annotation processor annotationProcessor("androidx.lifecycle:lifecycle-compiler:$lifecycle_version") // alternately - if using Java8, use the following instead of lifecycle-compiler implementation("androidx.lifecycle:lifecycle-common-java8:$lifecycle_version") // optional - helpers for implementing LifecycleOwner in a Service implementation("androidx.lifecycle:lifecycle-service:$lifecycle_version") // optional - ProcessLifecycleOwner provides a lifecycle for the whole application process implementation("androidx.lifecycle:lifecycle-process:$lifecycle_version") // optional - ReactiveStreams support for LiveData implementation("androidx.lifecycle:lifecycle-reactivestreams:$lifecycle_version") // optional - Test helpers for LiveData testImplementation("androidx.arch.core:core-testing:$arch_version") // optional - Test helpers for Lifecycle runtime testImplementation("androidx.lifecycle:lifecycle-runtime-testing:$lifecycle_version") }
如要進一步瞭解依附元件,請參閱「新增建構依附元件」一文。
意見回饋
您的意見可協助我們改善 Jetpack。如果您發現新問題,或是有改進這個程式庫的建議,請告訴我們。回報新問題前,請先查看這個程式庫的現有問題。只要按一下星號按鈕,即可投票給現有的問題。
詳情請參閱 Issue Tracker 文件。
2.8 版本
2.8.4 版
2024 年 7 月 24 日
發布 androidx.lifecycle:lifecycle-*:2.8.4
。2.8.4 版包含這些修訂版本。
修正錯誤
LiveData.asFlow()
現在可正確處理在收到LiveData
上設定的值後,傳回的資料流立即完成的情況 (例如使用take(1)
時)。(I9c566)。Lifecycle*Effect
完成度現在是冪等 (也就是說,如果onStopOrDispose
因 Lifecycle 停止而呼叫,除非生命週期再次回到STARTED
),否則在棄置時,系統不會再次呼叫該類別。(I5f607、b/352364595)
2.8.3 版
2024 年 7 月 1 日
發布 androidx.lifecycle:lifecycle-*:2.8.3
。2.8.3 版包含這些修訂版本。
修正錯誤
- 修正使用程式碼縮減時 Lifecycle 2.8 與 Compose 1.6.0 以下版本回溯相容性的問題。(aosp/3133056、b/346808608)
2.8.2 版
2024 年 6 月 12 日
發布 androidx.lifecycle:lifecycle-*:2.8.2
。2.8.2 版包含這些修訂版本。
修正錯誤
- 已修正將 Lifecycle 2.8.X 與 Compose 1.6.X 以下版本搭配使用時發生的
CompositionLocal LocalLifecycleOwner not present
錯誤,您現在可以將 Lifecycle 2.8.2 與任何 Compose 版本搭配使用,無需任何解決方法。(aosp/3105647、b/336842920) - 混用舊版
compileOnly
生命週期依附元件與 2.8 以上的版本時,ViewModelProvider
不會再停止運作,進而修正 LeakCanary 等程式庫的問題。(I80383、b/341792251)
2.8.1 版
2024 年 5 月 29 日
發布 androidx.lifecycle:lifecycle-*:2.8.1
。2.8.1 版包含這些修訂版本。
修正錯誤
lifecycle-viewmodel-compose
現在只有compose-runtime
有共同依附元件,移除了其在compose-ui
上的常見依附元件。Android 構件會保留compose-ui
以確保相容性。(aosp/3079334、b/339562627)- 使用屬性委派來的
ViewModel
整合saveable
現在會使用類別名稱做為自動產生的金鑰,避免在多個類別使用相同的SavedStateHandle
時發生衝突。(aosp/3063463)。
2.8.0 版
2024 年 5 月 14 日
發布 androidx.lifecycle:lifecycle-*:2.8.0
。2.8.0 版包含這些修訂版本。
自 2.7.0 版以來的重要異動
LocalLifecycleOwner
已從 Compose UI 移至lifecycle-runtime-compose
,因此可在 Compose UI 外使用其 Compose 輔助 API。lifecycle-runtime-compose
構件現在包含dropUnlessResumed
和dropUnlessStarted
API,可讓您在LifecycleOwner
降到指定的Lifecycle.State
以下之後,捨棄發生的點擊或其他事件。舉例來說,這項功能可與 Navigation Compose 搭配使用,避免在轉換至其他畫面後處理點擊事件:onClick: () -> Unit = dropUnlessResumed { navController.navigate(NEW_SCREEN) }
ViewModel.viewModelScope
現在是可覆寫的建構函式參數,可讓您插入自己的調度器和SupervisorJob()
,或使用runTest
中提供的backgroundScope
覆寫預設值。(I2817c、b/264598574)class MyViewModel( // Make Dispatchers.Main the default, rather than Dispatchers.Main.immediate viewModelScope: CoroutineScope = Dispatchers.Main + SupervisorJob() ) : ViewModel(viewModelScope) { // Use viewModelScope as before, without any code changes } // Allows overriding the viewModelScope in a test fun Test() = runTest { val viewModel = MyViewModel(backgroundScope) }
ViewModel
已在 Kotlin 中重新編寫,現在使用AutoClosable
而非Closeable
。現在支援使用key
新增AutoCloseable
物件,且該物件可透過getCloseable()
擷取。現在在不使用金鑰的情況下呼叫
LifecycleStartEffect
和LifecycleResumeEffect
會發生錯誤,遵循這些 API 所反映的DisposableEffect
API 慣例。淘汰
LiveDataReactiveStreams.toPublisher(lifecycleOwner, liveData)
,改用LiveData.toPublisher(lifecycleOwner)
。lifecycle-livedata-core-ktx
Kotlin 擴充功能現已移至lifecycle-livedata-core
模組。已重構
NullSafeMutableLiveData
,以避免過多的誤報。
生命週期 Kotlin 多平台相容性
Lifecycle
、LifecycleOwner
、LifecycleObserver
、Lifecycle.State
、Lifecycle.Event
和 LifecycleRegistry
中的核心 Lifecycle API 現在可透過與 Kotlin Multiplatform 相容的構件提供。
受影響的構件:
lifecycle-common
會將大多數 API 移至common
,並支援 Android 及 jvm 和 iOS。lifecycle-runtime
會將大多數 API 移至common
,並支援 Android 及 jvm 和 iOS。lifecycle-runtime-ktx
目前是空的,且所有 API 都會移到lifecycle-runtime
中。lifecycle-runtime-compose
會將所有 API 移至common
,並出貨與androidx.compose
的多平台支援相符的 Android 構件。
ViewModel Kotlin 多平台相容性
lifecycle-viewmodel
構件和 API (例如 ViewModel
、ViewModelStore
、ViewModelStoreOwner
和 ViewModelProvider
) 現已透過與 Kotlin Multiplatform 相容的構件提供。
為因應這項變更,現在使用 java.lang.Class<T>
的 ViewModelProvider
等方法,現在都已採用可接受 kotlin.reflect.KClass<T>
的對等方法。
Android 仍會維持二進位檔相容性,不過將 Android API 介面與常用 API 介面比較時,有一些明顯差異:
- 建構
ViewModelProvider
例項現在是透過ViewModelProvider.create()
方法完成,而不是直接呼叫其建構函式。 ViewModelProvider.NewInstanceFactory
和ViewModelProvider.AndroidViewModelFactory
僅適用於 Android。- 建議從
ViewModelProvider.Factory
擴充自訂工廠,並使用可接受CreationExtras
的create
方法,或使用viewModelFactory
Kotlin DSL。
- 建議從
- 在非 JVM 平台上沒有自訂工廠的情況下使用
ViewModelProvider
,會導致UnsupportedOperationException
。在 JVM 平台上,若未提供自訂工廠,使用 no-args ViewModel 建構函式即可保留相容性。 - 在無法使用
Dispatchers.Main
的平台 (例如viewModelScope
EmptyCoroutineContext
Linux)。
受影響的構件:
lifecycle-viewmodel
會將大多數 API 移至common
,並支援 Android 及 jvm 和 iOS。lifecycle-viewmodel-ktx
目前是空的,且所有 API 都會移到lifecycle-viewmodel
中。lifecycle-viewmodel-compose
會將所有 API 移至common
,並出貨與androidx.compose
的多平台支援相符的 Android 構件。
行為變更
- 如果新增具有相同
clazz: KClass<VM : ViewModel>
的initializer
,InitializerViewModelFactory
(包括viewModelFactory
建構工具函式) 現在會擲回IllegalArgumentException
。(Ic3a36)。
已知問題
lifecycle-*:2.8.0
需要 Compose 版本至少為 1.7.0-alpha05 (b/336842920)。
2.8.0-rc01 版
2024 年 5 月 1 日
發布 androidx.lifecycle:lifecycle-*:2.8.0-rc01
。2.8.0-rc01 版包含這些修訂版本。
修正錯誤
- 修正
lifecycle-common
類別的基準設定檔未正確封裝的問題。這些結果現已封裝在lifecycle-runtime
AAR 中。(aosp/3038274、b/322382422) - 修正了附加至 ViewModel 的
AutoCloseable
例項,意外排序異動 - 先前依序為addCloseable(String, AutoCloseable)
、addClosable(AutoCloseable)
和onCleared()
已經還原。(aosp/3041632)。 - 針對原生和 JVM 桌面環境改善
viewModelScope
的預設建立行為。(aosp/3039221)。
外部貢獻
- 感謝 Victor Kropp 改善 JVM 桌面上的主執行緒檢查效率。(aosp/3037116)。
2.8.0-beta01 版
2024 年 4 月 17 日
發布 androidx.lifecycle:lifecycle-*:2.8.0-beta01
。2.8.0-beta01 版包含這些修訂版本。
新功能
lifecycle-runtime-compose
構件現在與 Kotlin Multiplatform 相容,因此將其程式碼移至common
並出貨 Android 構件,與androidx.compose
的多平台支援功能相符。(If7a71、I4f4a0、b/331769623)
2.8.0-alpha04 版
2024 年 4 月 3 日
發布 androidx.lifecycle:lifecycle-*:2.8.0-alpha04
。2.8.0-alpha04 版包含這些修訂版本。
新功能
lifecycle-viewmodel-compose
構件現在與 Kotlin Multiplatform 相容,因此將其程式碼移至common
並出貨 Android 構件,與androidx.compose
的多平台支援功能相符。為因應這項變更,可組合函式的viewModel
方法現在除了java.lang.Class
以外,也接受KClass
。(b/330323282)。
修正錯誤
依附元件更新
lifecycle-viewmodel-compose
構件現在依附於 Compose 1.6.0。- Lifecycle 現在依附於 Profile Installer 1.3.1。
2.8.0-alpha03 版
March 20, 2024
發布 androidx.lifecycle:lifecycle-*:2.8.0-alpha03
。2.8.0-alpha03 版包含這些修訂版本。
新功能
ViewModel.viewModelScope
現在是可覆寫的建構函式參數,可讓您插入自己的調度器和SupervisorJob()
,或使用runTest
中提供的backgroundScope
覆寫預設值。(I2817c、b/264598574)class MyViewModel( // Make Dispatchers.Main the default, rather than Dispatchers.Main.immediate viewModelScope: CoroutineScope = Dispatchers.Main + SupervisorJob() ) : ViewModel(viewModelScope) { // Use viewModelScope as before, without any code changes } // Allows overriding the viewModelScope in a test fun Test() = runTest { val viewModel = MyViewModel(backgroundScope) }
Kotlin 多平台相容性
lifecycle-viewmodel
構件和 API (例如 ViewModel
、ViewModelStore
、ViewModelStoreOwner
和 ViewModelProvider
) 現已透過與 Kotlin Multiplatform 相容的構件提供。(b/214568825)。
為因應這項變更,現在使用 java.lang.Class<T>
的 ViewModelProvider
等方法,現在都已採用可接受 kotlin.reflect.KClass<T>
的對等方法。
Android 仍會維持二進位檔相容性,不過將 Android API 介面與常用 API 介面比較時,有一些明顯差異:
- 建構
ViewModelProvider
例項現在是透過ViewModelProvider.create()
方法完成,而不是直接呼叫其建構函式。 ViewModelProvider.NewInstanceFactory
和ViewModelProvider.AndroidViewModelFactory
僅適用於 Android。- 建議從
ViewModelProvider.Factory
擴充自訂工廠,並使用可接受CreationExtras
的create
方法,或使用viewModelFactory
Kotlin DSL。
- 建議從
- 在非 JVM 平台上沒有自訂工廠的情況下使用
ViewModelProvider
,會導致UnsupportedOperationException
。在 JVM 平台上,若未提供自訂工廠,使用 no-args ViewModel 建構函式即可保留相容性。 - 在無法使用
Dispatchers.Main
的平台 (例如viewModelScope
EmptyCoroutineContext
Linux)。
行為變更
- 如果新增具有相同
clazz: KClass<VM : ViewModel>
的initializer
,InitializerViewModelFactory
(包括viewModelFactory
建構工具函式) 現在會擲回IllegalArgumentException
。(Ic3a36)。
修正錯誤
ViewModel.getCloseable
現在會處理重複的金鑰:如果key
已有相關聯的AutoCloseable
資源,系統會立即替換並關閉舊資源。(Ibeb67)。- 現在存取
ViewModel
的viewModelScope
屬於執行緒安全。(If4766、b/322407038)
外部貢獻
LocalLifecycleOwner
已從 Compose UI 移至 Lifecycle-runtime-compose,因此可在 Compose UI 外使用以 Compose 為基礎的輔助 API。感謝 Jake Wharton 的貢獻。(I6c41b、b/328263448)
2.8.0-alpha02 版
2024 年 2 月 21 日
發布 androidx.lifecycle:lifecycle-*:2.8.0-alpha02
。查看 2.8.0-alpha02 版的修訂項。
新功能
- 已新增
dropUnlessResumed
和dropUnlessStarted
API,可讓您捨棄點擊或其他發生的事件,即使LifecycleOwner
已降到指定的Lifecycle.State
以下。舉例來說,這個方法可與 Navigation Compose 搭配使用,避免在轉換至其他畫面後處理點擊事件:onClick: () -> Unit = dropUnlessResumed { navController.navigate(NEW_SCREEN) }
(Icba83、b/317230685)
Kotlin 轉換
ViewModel
現在是以 Kotlin 編寫 (I16f26、b/214568825)lifecycle-viewmodel-ktx
Kotlin 擴充功能已移至基本生命週期模組。(Id787b、b/274800183)lifecycle-runtime-ktx
Kotlin 擴充功能已移至基本生命週期模組。(Ic3686、b/274800183)lifecycle-livedata-core-ktx
Kotlin 擴充功能已移至基本生命週期模組。(I54a3d、b/274800183)
Kotlin 多平台相容性
Lifecycle
、LifecycleOwner
、LifecycleObserver
、Lifecycle.State
、Lifecycle.Event
和LifecycleRegistry
中的核心 Lifecycle API 現在可透過與 Kotlin Multiplatform 相容的構件提供。(b/317249252)。
API 變更
- 現在在不使用金鑰的情況下呼叫
LifecycleStartEffect
和LifecycleResumeEffect
會發生錯誤,遵循這些 API 所反映的DisposableEffect
API 慣例。(Ib0e0c、b/323518079) ViewModel
現在使用AutoCloseable
,而不是Closeable
。這是回溯相容的變更。(I27f8e、b/214568825)- 淘汰
LiveDataReactiveStreams.toPublisher(lifecycleOwner, liveData)
,改用LiveData.toPublisher(lifecycleOwner)
。(Iabe29、b/262623005)
外部貢獻
- 感謝 Jetbrains 的 Ivan Matkov 可幫助您將生命週期移至 Kotlin Multiplatform。(aosp/2926690、I0c5ac、If445d)
2.8.0-alpha01 版
2024 年 1 月 24 日
發布 androidx.lifecycle:lifecycle-*:2.8.0-alpha01
。查看 2.8.0-alpha01 版的修訂項。
新功能
ViewModel
現在支援使用key
新增Closeable
物件,該物件可透過getCloseable()
擷取。(I3cf63)。
2.7 版
2.7.0 版
2024 年 1 月 10 日
發布 androidx.lifecycle:lifecycle-*:2.7.0
。查看 2.7.0 版的修訂項。
自 2.6.0 版以來的重要變更
TestLifecycleOwner
現在包含暫停函式setCurrentState()
,可確保狀態變更及所有LifecycleObserver
回呼在傳回前完成。值得注意的是,與直接設定currentState
屬性不同,這不會使用runBlocking
,因此可以在如runTest
提供的協同程式中安全地使用。map
和switchMap
的LiveData
擴充功能現在會反映distinctUntilChanged
的行為;如果LiveData
已設定value
,系統會「立即」呼叫map
/switchMap
函式,以填入回傳LiveData
的value
。這可確保初始值會設為第一個組合的一部分 (與observeAsState()
搭配使用時),但不會變更觀察行為,因此只有在您開始觀察LiveData
時,才會套用來源LiveData
的值更新。- 這個版本修正了
SavedStateHandle
在程序終止並重建後,無法正確還原自訂Parcelable
類別的問題。由於 Android 架構遺失的類型資訊,自訂 Parcelable 的陣列需要額外的工作 (手動建立正確類型的型別陣列),且get
、getLiveData
和getStateFlow
的說明文件現在特別呼叫這項限制。 - 已移除與
LifecycleObserver
相關聯的 ProGuard 保留規則。也就是說,如果保護程式碼想要透過反射來使用 API (例如使用已淘汰的@OnLifecycleEvent
註解至今的時長),就必須針對特定用途提供專屬保留規則。
生命週期事件觀測功能
- 除了使用
LifecycleEventObserver
以外,您現在可透過Lifecycle.asFlow()
擴充功能方法觀察Lifecycle.Event
的Flow
。 - Jetpack Compose 使用者現在可以使用
LifecycleEventEffect
,根據Lifecycle.Event
執行 Compose 連帶效果。
@Composable
fun HomeScreen(viewModel: HomeViewModel = viewModel()) {
LifecycleEventEffect(Lifecycle.Event.ON_RESUME) {
viewModel.refreshData()
}
// …
}
- Jetpack Compose 使用者可以使用
LifecycleStartEffect
和LifecycleResumeEffect
處理事件的「配對」,分別啟動已停止和繼續暫停期間。這個 API 會反映DisposableEffect
中的值,適用於狀態向上時變更的情況。
fun HomeScreen(viewModel: HomeViewModel = viewModel()) {
LifecycleStartEffect(viewModel) {
val timeTracking = viewModel.startTrackingTimeOnScreen()
onStopOrDispose {
timeTracking.stopTrackingTimeOnScreen()
}
}
// …
}
詳情請參閱「在生命週期事件中執行程式碼」。
生命週期狀態觀測功能
- 您現在可透過
Lifecycle.currentStateFlow
屬性觀察目前的Lifecycle.State
,這個屬性會傳回StateFlow
,其中value
是目前的Lifecycle.State
。 - Jetpack Compose 使用者可以使用
Lifecycle.currentStateAsState()
擴充功能,將Lifecycle.State
直接公開為 ComposeState
。這等同於lifecycle.currentStateFlow.collectAsState()
(且較短的替代版本)。
詳情請參閱「透過資料流收集生命週期狀態」。
2.7.0-rc02 版
2023 年 12 月 13 日
發布 androidx.lifecycle:lifecycle-*:2.7.0-rc02
。查看 2.7.0-rc02 版的修訂項。
修正錯誤
- 修正了在程序終止並重建後,
SavedStateHandle
無法正確還原自訂Parcelable
類別的問題。由於 Android 架構遺失的類型資訊,自訂 Parcelable 的陣列需要額外的工作 (手動建立正確類型的型別陣列),且get
、getLiveData
和getStateFlow
的說明文件現在特別呼叫這項限制。(I0b55a)。
2.7.0-rc01 版
2023 年 11 月 15 日
發布 androidx.lifecycle:lifecycle-*:2.7.0-rc01
。查看 2.7.0-rc01 版的修訂項。
修正錯誤
- 如果
LifecycleOwner
有所變更,LifecycleStartEffect
和LifecycleResumeEffect
現在可正確處置並重新建立效果區塊。(Ia25c6)。
2.7.0-beta01 版
2023 年 11 月 1 日
androidx.lifecycle:lifecycle-*:2.7.0-beta01
發布,內容無變更。查看 2.7.0-beta01 版的修訂項。
- 提供 Beta 版更新,但此發布版本沒有重大變更。
2.7.0-alpha03 版
2023 年 10 月 18 日
發布 androidx.lifecycle:lifecycle-*:2.7.0-alpha03
。查看 2.7.0-alpha03 版的修訂項。
新功能
lifecycle-runtime-testing
現在包含新的 Lint 檢查,可避免在協同程式內使用currentState
欄位,而設定TestLifecycleOwner
的Lifecycle.State
。Lint 檢查現在建議暫停setCurrentState
,以便在不封鎖的情況下設定Lifecycle.State
。(Icf728、b/297880630)
修正錯誤
- 修正
LiveData.switchMap
的問題:在初始呼叫和後續呼叫中都傳回同一個LiveData
執行個體,會導致系統無法將LiveData
例項新增為來源。(Ibedcba7)。
2.7.0-alpha02 版
2023 年 9 月 6 日
發布 androidx.lifecycle:lifecycle-*:2.7.0-alpha02
。查看 2.7.0-alpha02 版的修訂項。
新功能
TestLifecycleOwner
現在包含暫停函式setCurrentState()
,可讓使用者在協同程式 (例如runTest
提供的協同程式) 內使用TestLifecycleOwner
。(I329de、b/259344129)
API 變更
lifecycle-livedata-ktx
模組的所有檔案已移至主要lifecycle-livedata
模組。(I10c6f、b/274800183)
行為變更
- 如果先前的
LiveData
已設定值,LiveData.map()
和LiveData.switchMap()
擴充功能現在會設定傳回的LiveData
的value
,確保在 Jetpack Compose 中使用產生的 LiveData 具有正確的初始組合狀態。(I91d2b、b/269479952) - 如果
ViewModel
已收到對onCleared()
的呼叫,ViewModel
的addCloseable()
現在會立即關閉Closeable
。(I4712e、b/280294730)
修正錯誤
- 自 Lifecycle
2.6.2
起:修正了以下問題:如果還原狀態,SavedStateHandle
無法在程序終止後正確還原,則呼叫save()
時不會實際在父項SavedStateRegistry
中儲存狀態,之後狀態就會再次還原。這修正了rememberSaveable
與 Navigation ComposeNavHost
之間的互動。(aosp/2729289)。
2.7.0-alpha01 版
2023 年 7 月 26 日
發布 androidx.lifecycle:lifecycle-*:2.7.0-alpha01
。查看 2.7.0-alpha01 版的修訂項。
API 變更
Lifecycle.State
現在可透過Lifecycle.currentStateFlow
觀察 Compose 了,後者會傳回value
是目前Lifecycle.State
的StateFlow
。(Ib212d、b/209684871)- 現在可以使用
Lifecycle.asFlow().
將Lifecycle.Event
視為Flow
(If2c0f、b/176311030) - 新增了
LifecycleResumeEffect
API,以便根據Lifecycle.Event.ON_RESUME
和Lifecycle.Event.ON_PAUSE
事件回呼執行 ComposeSideEffect
。(I60386、b/235529345) - 新增了
LifecycleStartEffect
API,以便根據Lifecycle.Event.ON_START
和Lifecycle.Event.ON_STOP
事件回呼執行 ComposeSideEffect
。(I5a8d1、b/235529345) - 新增了
LifecycleEventEffect
API,以便根據Lifecycle.Event
執行 ComposeSideEffect
。(Ic9794、b/235529345) - 新增
Lifecycle.collectAsState()
擴充功能,可將Lifecycle.State
直接公開為 ComposeState
。這等同於lifecycle.currentStateFlow.collectAsState()
(且較短的替代版本)。(I11015、b/235529345)
修正錯誤
- 如果先前的
LiveData
已設定值,LiveData.distinctUntilChanged()
擴充功能現在會設定傳回的LiveData
的value
。這不會影響觀察行為,只有在您開始觀察distinctUntilChanged()
傳回的LiveData
後,來源LiveData
中的更新值才會套用。(Ib482f)。 - 已移除與
LifecycleObserver
相關聯的 ProGuard 保留規則。這表示,為了讓透過反射而使用 API 的保護程式碼,必須針對其特定用途提供專屬保留規則。(Ia12fd)。
2.6 版本
2.6.2 版
2023 年 9 月 6 日
發布 androidx.lifecycle:lifecycle-*:2.6.2
。查看 2.6.2 版的修訂項。
修正錯誤
- 修正了以下問題:如果還原狀態,
SavedStateHandle
無法在程序終止後正確還原,呼叫save()
時並未實際在父項SavedStateRegistry
中儲存狀態,之後狀態就會再次還原這修正了rememberSaveable
與 Navigation ComposeNavHost
之間的互動。(aosp/2729289)。
2.6.1 版
2023 年 3 月 22 日
發布 androidx.lifecycle:lifecycle-*:2.6.1
。查看 2.6.1 版的修訂項。
依附元件更新
lifecycle-viewmodel-savedstate
現在依附於 SavedState1.2.1
(cd7251)。- 生命週期現在依附於 ProfileInstaller
1.3.0
。(f9d30b)。
2.6.0 版
2023 年 3 月 8 日
發布 androidx.lifecycle:lifecycle-*:2.6.0
。查看 2.6.0 版的修訂項。
自 2.5.0 版以來的重要變更
LiveData
現在包含新的isInitialized
屬性,可指出LiveData
是否已設定明確的值,方便您區分liveData.value
會傳回null
(因為未設定任何值),還是明確的null
值。MediatorLiveData
現在包含用來設定初始值的建構函式。- 在
StateFlow
和Flow
的collectAsStateWithLifecycle()
上新增擴充功能,以生命週期感知方式收集並表示其最新值為 Compose 狀態。 Lifecycle.launchWhenX
方法和Lifecycle.whenX
方法已淘汰,因為在某些情況下,使用暫停調度工具可能會導致資源浪費。建議使用Lifecycle.repeatOnLifecycle
。如要進一步瞭解一次性停權工作,請參閱這個說明,瞭解這麼做本身並不安全的原因。- Kotlin 轉換:大量的 Lifecycle 類別已轉換為 Kotlin。所有已轉換的類別仍保有與先前版本的二進位檔相容性。下列類別對以 Kotlin 編寫的類別進行與原始碼不相容的變更:
ViewTreeLifecycleOwner
、LiveDataReactiveStreams
、HasDefaultViewModelProviderFactory
、ViewTreeViewModelStoreOwner
、Transformations
、ViewModelStoreOwner
、LifecycleOwner
下表列出新版生命週期的來源轉換。
生命週期 2.5 | 生命週期 2.5 (KTX) | 生命週期 2.6 |
---|---|---|
Transformations.switchMap(liveData) {...} |
liveData.switchMap {...} |
liveData.switchMap {...} |
Transformations.map(liveData) {...} |
liveData.map {...} |
liveData.map {...} |
Transformations.distinctUntilChanged(liveData) {...} |
liveData.distinctUntilChanged{...} |
liveData.distinctUntilChanged{...} |
LiveDataReactiveStreams.fromPublisher(publisher) |
publisher.toLiveData() |
publisher.toLiveData() |
LiveDataReactiveStreams.toPublisher(lifecycleOwner, liveData) |
liveData.toPublisher(lifecycleOwner) |
liveData.toPublisher(lifecycleOwner) |
override fun getDefaultViewModelProviderFactory(): ViewModelProvider.Factory = factory |
override fun getDefaultViewModelProviderFactory(): ViewModelProvider.Factory = factory |
override val defaultViewModelProviderFactory = factory |
override fun getDefaultViewModelCreationExtras(): CreationExtras = extras |
override fun getDefaultViewModelCreationExtras(): CreationExtras = extras |
override val defaultViewModelProviderCreationExtras = extras |
ViewTreeLifecycleOwner.set(view, owner) |
ViewTreeLifecycleOwner.set(view, owner) |
view.setViewTreeLifecycleOwner(owner) |
ViewTreeLifecycleOwner.get(view) |
view.findViewTreeLifecycleOwner() |
view.findViewTreeLifecycleOwner() |
override fun getViewModelStore(): ViewModelStore = store |
override fun getViewModelStore(): ViewModelStore = store |
override val viewModelStore: ViewModelStore = store |
override fun getLifecycle(): Lifecycle = registry |
override fun getLifecycle(): Lifecycle = registry |
override val lifecycle: Lifecycle get() = registry |
- 在 Kotlin 中建立的
Observer
的onChanged
方法是否可為空值,現與泛型類型的「是否可為空值」相符。如果您想讓Observer.onChanged()
接受可為空值類型,就必須使用可為空值類型將Observer
執行個體化。 - 這些類別也已轉換為 Kotlin,但與原始碼相容:
DefaultLifecycleObserver
、LifecycleEventObserver
、Lifecycle
、LifecycleRegistry
、LifecycleObserver
、ViewModelStore
、AndroidViewModel
、AbstractSavedStateViewModelFactory
、LifecycleService
、ServiceLifecycleDispatcher
和ProcessLifecycleOwner
2.6.0-rc01 版
2023 年 2 月 22 日
發布 androidx.lifecycle:lifecycle-*:2.6.0-rc01
。查看 2.6.0-rc01 版的修訂項。
修正錯誤
- 如果先前的
LiveData
已設定值,LiveData.distinctUntilChanged()
擴充功能現在會設定傳回的LiveData
的value
。這不會影響觀察行為,只有在您開始觀察distinctUntilChanged()
傳回的LiveData
後,來源LiveData
中的更新值才會套用。(Ib482f)。
2.6.0-beta01 版
2023 年 2 月 8 日
發布 androidx.lifecycle:lifecycle-*:2.6.0-beta01
。2.6.0-beta01 版包含此連結所列的修訂項目。
Kotlin 轉換
LifecycleOwner
現在以 Kotlin 編寫。對以 Kotlin 編寫的類別而言,這是與來源不相容的變更,因此這些類別現在必須覆寫lifecycle
屬性,而不是導入先前的getLifecycle()
函式 (I75b4b、b/240298691)。ViewModelStoreOwner
現在以 Kotlin 編寫。對以 Kotlin 編寫的類別而言,這是與來源不相容的變更,因此這些類別現在必須覆寫viewModelStore
屬性,而不是導入先前的getViewModelStore()
函式 (I86409、b/240298691)。- 在提供
lifecycleScope
欄位的LifecycleOwner
上,Kotlin 擴充功能已從lifecycle-runtime-ktx
移至lifecycle-common
構件 (I41d78、b/240298691)。 - 在提供
coroutineScope
欄位的Lifecycle
上,Kotlin 擴充功能已從lifecycle-runtime-ktx
移至lifecycle-common
構件 (Iabb91、b/240298691)。
2.6.0-alpha05 版
2023 年 1 月 25 日
發布 androidx.lifecycle:lifecycle-*:2.6.0-alpha05
。2.6.0-alpha05 版包含此連結所列的修訂項目。
Kotlin 轉換
Transformations
現在以 Kotlin 編寫。對於以 Kotlin 編寫且直接使用Transformations.map
等語法的類別,這屬於與原始碼不相容的異動,因此現在 Kotlin 程式碼必須使用 Kotlin 擴充功能方法語法,這個語法先前只有在使用lifecycle-livedata-ktx
時才能使用。使用 Java 程式設計語言時,如果這些方法的版本採用androidx.arch.core.util.Function
方法,則會遭淘汰,並由採用 KotlinFunction1
的版本取代。這項變更仍保有二進位檔相容性 (I8e14f)。ViewTreeViewModelStoreOwner
現在以 Kotlin 編寫。對於以 Kotlin 編寫的類別,這屬於與原始碼不相容的異動,因此您現在必須為androidx.lifecycle.setViewTreeViewModelStoreOwner
和androidx.lifecycle.findViewTreeViewModelStoreOwner
的View
直接匯入並使用 Kotlin 擴充功能方法,才能設定及找出先前設定的擁有者。另外,這與二進位檔相容,而且以 Java 程式設計語言編寫的實作仍保持原始碼相容性 (Ia06d8、Ib22d8、b/240298691)。HasDefaultViewModelProviderFactory
介面現在以 Kotlin 編寫。對於以 Kotlin 編寫的類別,這屬於與原始碼不相容的異動,因此這些類別現在必須覆寫defaultViewModelProviderFactory
和defaultViewModelCreationExtras
屬性,而不是實作先前的對應函式 (Iaed9c、b/240298691)。Observer
現在以 Kotlin 編寫。其onChanged()
方法現在使用value
名稱做為參數 (Iffef2、I4995e、b/240298691)。AndroidViewModel
、AbstractSavedStateViewModelFactory
、LifecycleService
、ServiceLifecycleDispatcher
和ProcessLifecycleOwner
現在以 Kotlin 編寫 (I2e771、Ibae40、I160d7、I08884、I1cda7、b/240298691)
2.6.0-alpha04 版
2023 年 1 月 11 日
發布 androidx.lifecycle:lifecycle-*:2.6.0-alpha04
。查看 2.6.0-alpha04 版的修訂項。
新功能
LiveData
現在提供新的isInitialized
屬性,可指出LiveData
是否曾設定明確的值,方便您辨別liveData.value
傳回null
是因為未設定任何值,還是因為已設定明確的null
值 (Ibd018)。
API 變更
lifecycle-runtime-compose
的collectAsStateWithLifecycle()
API 已不再處於實驗狀態 (I09d42、b/258835424)。Lifecycle.launchWhenX
方法和Lifecycle.whenX
方法已淘汰,因為在某些情況下,使用暫停調度工具可能會導致資源浪費。建議使用Lifecycle.repeatOnLifecycle
(Iafc54、b/248302832)。
Kotlin 轉換
ViewTreeLifecycleOwner
現在是以 Kotlin 編寫。對使用 Kotlin 程式語言編寫的類別而言,這項變更具有來源不相容性,因此您現在必須在androidx.lifecycle.setViewTreeLifecycleOwner
和androidx.lifecycle.findViewTreeLifecycleOwner
的View
上,直接匯入並使用 Kotlin 擴充功能方法,才能設定及找出先前設定的擁有者。這會取代lifecycle-runtime-ktx
中的舊版 Kotlin 擴充功能,另外,這與二進位檔相容,而且以 Java 程式設計語言編寫的實作仍保持原始碼相容性 (I8a77a、I5234e、b/240298691)。LiveDataReactiveStreams
現在是以 Kotlin 編寫。lifecycle-reactivestreams-ktx
中的舊版 Kotlin 擴充功能已移至lifecycle-reactivestreams
模組,並針對以 Kotlin 編寫的程式碼成為主要途徑。如果您並未使用 Kotlin 擴充功能方法 API,這項變更對於使用 Kotlin 編寫的程式碼而言,具有來源不相容性 (I2b1b9、I95d22、b/240298691)。DefaultLifecycleObserver
、LifecycleEventObserver
、Lifecycle
、LifecycleRegistry
、LifecycleObserver
和ViewModelStore
現在是以 Kotlin 編寫 (Iadffd、I60034、I8c52c、I9593d、I01fe1、I59a23、b/240298691)。
修正錯誤
- 使用錯誤的類別類型呼叫
get()
時,SavedStateHandle
不會再發生ClassCastException
的異常終止 (I6ae7c)。
2.6.0-alpha03 版
2022 年 10 月 24 日
發布 androidx.lifecycle:lifecycle-*:2.6.0-alpha03
。查看 2.6.0-alpha03 版的修訂項。
修正錯誤
- 修正了不同 Lifecycle 模組之間無法如預期正常運作的問題 (I18d0d、b/249686765)。
LifecycleRegistry.moveToState()
擲回的錯誤現在會提供更實用的錯誤訊息,讓開發人員瞭解導致發生錯誤的元件 (Idf4b2、b/244910446)。
2.6.0-alpha02 版
2022 年 9 月 7 日
發布了 androidx.lifecycle:lifecycle-*:2.6.0-alpha02
。2.6.0-alpha02 版包含此連結所列的修訂項目。
API 變更
MediatorLiveData
現在包含用於設定初始值的建構函式 (Ib6cc5、b/151244085)。
修正錯誤
Lifecycle
構件現在有了多項限制,確保所有彼此依附的 Lifecycle 構件使用相同的版本。換句話說,當其中一個構件升級時,其他依附元件也會自動升級 (b/242871265)。FlowLiveData.asFlow()
現在會建立callbackFlow
(而不是使用自己的Channel
實作項目),確保執行緒安全並保留結構定義 (I4a8b2、b/200596935)。FlowLiveData
的asLiveData
函式現在會在建立新的LiveData
物件時保留StateFlow
的初始值 (I3f530、b/157380488)。- 自 Lifecycle
2.5.1
版起:將有狀態的建構函式與Lifecycle
2.4 以上版本搭配使用時,AndroidViewModelFactory
的自訂實作項目現在會正確呼叫create(modelClass)
(I5b315、b/238011621)。
2.6.0-alpha01 版
2022 年 6 月 29 日
發布了 androidx.lifecycle:lifecycle-*:2.6.0-alpha01
。查看 2.6.0-alpha01 版的修訂項。
新功能
- 新增
collectAsStateWithLifecycle
的StateFlow
和Flow
擴充功能,可從資料流收集,並以生命週期感知方式的 Compose 狀態代表其最新的值。系統會收集資料流,然後當生命週期至少為特定的Lifecycle.State
時,將新的傳輸設為狀態的值。當生命週期值低於Lifecycle.State
時,系統就會停止收集資料流,且不會更新狀態的值 (I1856e、b/230557927)。
2.5 版
2.5.1 版
2022 年 7 月 27 日
發布了 androidx.lifecycle:lifecycle-*:2.5.1
。2.5.1 版包含此連結所列的修訂項目。
修正錯誤
- 現在搭配
Lifecycle
2.4 以上版本使用有狀態的AndroidViewModelFactory
建構函式時,AndroidViewModelFactory
的自訂實作可以正確呼叫create(modelClass)
函式 (I5b315、b/238011621)。
2.5.0 版
2022 年 6 月 29 日
發布了 androidx.lifecycle:lifecycle-*:2.5.0
。2.5.0 版包含此連結所列的修訂項目。
自 2.4.0 版以來的重要異動
SavedStateHandle
現在提供getStateFlow()
API,可傳回 KotlinStateFlow
監控值的變化,適合做為LiveData
的替代方案。ViewModel CreationExtras - 撰寫自訂的
ViewModelProvider.Factory
時,不再需要擴充AndroidViewModelFactory
或AbstractSavedStateViewModelFactory
個別取得Application
或SavedStateHandle
的存取權,而是會透過create(Class<T>, CreationExtras)
新的create
超載,將這些欄位提供給「所有」ViewModelProvider.Factory
子類別做為CreationExtras
。這些額外的功能會在分別使用 Activity1.5.0
和 Fragment1.5.0
時,自動由 Activity 或 Fragment 提供。class CustomFactory : ViewModelProvider.Factory { override fun <T : ViewModel> create(modelClass: Class<T>, extras: CreationExtras): T { return when (modelClass) { HomeViewModel::class -> { // Get the Application object from extras val application = checkNotNull(extras[ViewModelProvider.AndroidViewModelFactory.APPLICATION_KEY]) // Pass it directly to HomeViewModel HomeViewModel(application) } DetailViewModel::class -> { // Create a SavedStateHandle for this ViewModel from extras val savedStateHandle = extras.createSavedStateHandle() DetailViewModel(savedStateHandle) } else -> throw IllegalArgumentException("Unknown class $modelClass") } as T } }
lifecycle-viewmodel
現在提供viewModelFactory
Kotlin DSL,可讓您根據一或多個 lambda 初始化器定義ViewModelProvider.Factory
,而且會以CreationExtras
為主要的資料來源,為自訂工廠支援的每個特定ViewModel
類別各定義一個。val customFactory = viewModelFactory { // The return type of the lambda automatically sets what class this lambda handles initializer { // Get the Application object from extras provided to the lambda val application = checkNotNull(get(ViewModelProvider.AndroidViewModelFactory.APPLICATION_KEY)) HomeViewModel(application) } initializer { val savedStateHandle = createSavedStateHandle() DetailViewModel(savedStateHandle) } }
lifecycle-viewmodel-compose
現在提供viewModel()
API,可運用 lambda 工廠建立ViewModel
執行個體,無須建立自訂的ViewModelProvider.Factory
。// Within a @Composable, you can now skip writing a custom Factory // and instead write a lambda to do the initialization of your ViewModel val detailViewModel = viewModel { // This lambda is only called the first time the ViewModel is created // and all CreationExtras are available inside the lambda val savedStateHandle = createSavedStateHandle() DetailViewModel(savedStateHandle) }
SavedStateHandle Compose Saver 整合 -
lifecycle-viewmodel-compose
構件現在於SavedStateHandle.saveable
中包含新的實驗性 API,允許由 ViewModel 的SavedStateHandle
備份rememberSaveable
(例如行為)。class ListScreenViewModel(handle: SavedStateHandle): ViewModel() { // This value survives both configuration changes and process death and recreation val editMode by handle.saveable { mutableStateOf(false) } }
新增了
addCloseable()
API 和新的建構函式超載,可讓您在ViewModel
中加入一或多個Closeable
物件,這些物件會在ViewModel
清除時關閉,無須在onCleared()
中進行任何手動操作。舉例來說,如要建立可插入 ViewModel 的協同程式範圍,但要能夠透過測試控制,您可以建立實作
Closeable
的CoroutineScope
:class CloseableCoroutineScope( context: CoroutineContext = SupervisorJob() + Dispatchers.Main.immediate ) : Closeable, CoroutineScope { override val coroutineContext: CoroutineContext = context override fun close() { coroutineContext.cancel() } }
然後就可於
ViewModel
建構函式中使用,同時維持與viewModelScope
相同的生命週期:class TestScopeViewModel( val customScope: CloseableCoroutineScope = CloseableCoroutineScope() ) : ViewModel(customScope) { // You can now use customScope in the same way as viewModelScope }
行為變更
- 現在如果嘗試將
Lifecycle.State
從INITIALIZED
移至DESTROYED
,則不論Lifecycle
是否附有觀察器,一律都會擲回IllegalStateException
。 - 現在
LifecycleRegistry
於達到DESTROYED
狀態後會清除其觀測器。
2.5.0-rc02 版
2022 年 6 月 15 日
發布了 androidx.lifecycle:lifecycle-*:2.5.0-rc02
。查看 2.5.0-rc02 版的修訂項。
修正錯誤
- 混合使用舊版 compileOnly Lifecycle 依附元件與 2.5 以上版本時,
ViewModelProvider
不會再發生當機情形。(I81a66、b/230454566)
2.5.0-rc01 版
2022 年 5 月 11 日
發布 androidx.lifecycle:lifecycle-*:2.5.0-rc01
。2.5.0-rc01 版包含此連結所列的修訂項目。
修正錯誤
MediatorLiveData.addSource()
現在接收到null
來源時會擲回NullPointerException
,而不會將null
來源套用到觀察器 (Ibd0fb、b/123085232)。
2.5.0-beta01 版
2022 年 4 月 20 日
發布 androidx.lifecycle:lifecycle-*:2.5.0-beta01
。2.5.0-beta01 版包含此連結所列的修訂項目。
API 變更
- 新增
SavedStateHandle.saveable
屬性委派項目,以便使用屬性名稱做為鍵,將狀態保存到SavedStateHandle
中 (I8bb86、b/225014345)
修正錯誤
- 修正問題:使用多個返回堆疊時,將非主要底部導航分頁中的一個
NavHost
巢狀至另一個NavHost
時會導致IllegalStateException
。(I11bd5、b/228865698)
2.5.0-alpha06 版
2022 年 4 月 6 日
發布了 androidx.lifecycle:lifecycle-*:2.5.0-alpha06
。2.5.0-alpha06 版包含此連結所列的修訂項目。
新功能
- 將實驗性
MutableState
超載新增至SavedStateHandle.saveable
,與rememberSaveable
保持一致 (I38cfe、b/224565154)
API 變更
CreationExtras
現已改為抽象而非密封。(Ib8a7a)
修正錯誤
- 修正了
SavedStateHandleController
造成的IllegalStateException: Already attached to lifecycleOwner
錯誤。(I7ea47、b/215406268)
2.5.0-alpha05 版
2022 年 3 月 23 日
發布了 androidx.lifecycle:lifecycle-*:2.5.0-alpha05
。2.5.0-alpha05 版包含此連結所列的修訂項目。
新功能
lifecycle-viewmodel-compose
模組現在提供SavedStateHandleSaver
,這項實驗性 API 可確保SavedStateHandle
中的值與rememberSaveable
使用的相同儲存執行個體狀態正確整合。(Ia88b7、b/195689777)
API 變更
- 修正了與 Java 中 Lifecycle 2.3 及更新版本 Lifecycle 的相容性問題。(I52c8a、b/219545060)
修正錯誤
SavedStateViewFactory
現在支援使用CreationExtras
(即使已透過SavedStateRegistryOwner
初始化)。如果提供額外項目,系統將忽略初始化的引數 (I6c43b、b/224844583)
2.5.0-alpha04 版
2022 年 3 月 9 日
發布了 androidx.lifecycle:lifecycle-*:2.5.0-alpha04
。2.5.0-alpha04 版包含此連結所列的修訂項目。
API 變更
SavedStateHandle
現在提供getStateFlow()
API,可傳回 KotlinStateFlow
來協助監控值的變化,適合做為LiveData
的替代方案 (Iad3ab,b/178037961)
2.5.0-alpha03 版
2022 年 2 月 23 日
發布 androidx.lifecycle:lifecycle-*:2.5.0-alpha03
。2.5.0-alpha03 版包含此連結所列的修訂項目。
新功能
- 新增了
addCloseable()
API 和新的建構函式超載,可讓您在ViewModel
中加入一或多個Closeable
物件,這些物件會在ViewModel
清除時關閉,無須在onCleared()
中進行任何手動操作 (I55ea0) lifecycle-viewmodel
現在提供InitializerViewModelFactory
,讓您新增 lambda 來處理特定的ViewModel
類別,所用主要資料來源為CreationExtras
。(If58fc,b/216687549)lifecycle-viewmodel-compose
現在提供viewModel()
API,可運用 lambda 工廠建立ViewModel
執行個體,無須建立自訂ViewModelProvider.Factory
(I97fbb,b/216688927)
API 變更
- 您現在可以透過
lifecycle-viewmodel-compose
使用CreationExtras
建立ViewModel
(I08887,b/216688927)
行為變更
- 現在如果嘗試將
Lifecycle.State
從INITIALIZED
移至DESTROYED
,則不論Lifecycle
是否附有觀察器,一律都會擲回IllegalStateException
(I7c390,b/177924329) - 現在
LifecycleRegistry
達到DESTROYED
狀態後會清除其觀察器 (I4f8dd,b/142925860)
2.5.0-alpha02 版
2022 年 2 月 9 日
發布 androidx.lifecycle:lifecycle-*:2.5.0-alpha02
。2.5.0-alpha02 版包含此連結所列的修訂項目。
API 變更
SavedStateHandle
和SavedStateViewModelFactory
已轉換成 Kotlin,改善了這兩個類別中一般項目的「是否可為空值」屬性。 (Ib6ce2,b/216168263;I9647a,b/177667711)LiveData
switchMap
函式參數的輸出值現在可設為空值。(I40396,b/132923666)LiveData
-ktx 擴充功能現在會加註@CheckResult
,強制在呼叫這些函式時使用該結果 (Ia0f05,b/207325134)
行為變更
- 現在當指定的索引鍵沒有值時,
SavedStateHandle
會適當地儲存 defaultValue。(I1c6ce,b/178510877)
修正錯誤
- Lifecycle
2.4.1
:更新了lifecycle-process
,改為依附於 Startup 1.1.1,以確保修正項目預設可供使用,防止ProcessLifecycleInitializer
擲回StartupException
。(Ib01df,b/216490724) - 現在當自訂
AndroidViewModel
類別的參數順序有誤且嘗試建立ViewModel
時,系統會顯示更完善的錯誤訊息 (I340f7,b/177667711) - 您現在可以透過
CreationExtras
使用AndroidViewModelFactory
建立檢視模型,不必設定應用程式 (I6ebef,b/217271656)
2.5.0-alpha01 版
2022 年 1 月 26 日
發布 androidx.lifecycle:lifecycle-*:2.5.0-alpha01
。2.5.0-alpha01 版包含此連結所列的修訂項目。
ViewModel CreationExtras
在這個版本中,我們將為重塑 ViewModel
的建構方式打好基礎。我們不會採用一組既定的 ViewModelProvider.Factory
子類別分別加入額外的功能 (透過 AndroidViewModelFactory
允許使用 Application
建構函式參數、透過 SavedStateViewModelFactory
和 AbstractSavedStateViewModelFactory
允許使用 SavedStateHandle
建構函式參數等等),而會改用以全新概念 CreationExtras
為基礎的無狀態工廠。(Ia7343,b/188691010、b/188541057)
這項異動生效後,ViewModelProvider
不會再直接呼叫 ViewModelProvider.Factory
先前的 create(Class<T>)
方法,而會改為呼叫 create
的全新多載方法:create(Class<T>, CreationExtras)
。這表示現在只要直接導入 ViewModelProvider.Factory
執行個體,即可存取這些新的 CreationExtras
:
ViewModelProvider.NewInstanceFactory.VIEW_MODEL_KEY
:這個String
可讓您存取傳送到ViewModelProvider.get()
的自訂鍵。ViewModelProvider.AndroidViewModelFactory.APPLICATION_KEY
可讓您存取Application
類別。SavedStateHandleSupport.SAVED_STATE_REGISTRY_OWNER_KEY
可讓您存取目前用於建構這個 ViewModel 的SavedStateRegistryOwner
。SavedStateHandleSupport.VIEW_MODEL_STORE_OWNER_KEY
可讓您存取目前用於建構這個 ViewModel 的ViewModelStoreOwner
。SavedStateHandleSupport.DEFAULT_ARGS_KEY
可讓您存取要用於建構SavedStateHandle
的引數Bundle
。
使用 Activity 1.5.0-alpha01
、Fragment 1.5.0-alpha01
和 Navigation 2.5.0-alpha01
時,系統預設會提供這些額外項目。如果您使用舊版程式庫,CreationExtras
將是空白的;ViewModelProvider.Factory
的所有現有子類別皆經過改寫,以同時支援舊版程式庫所使用的舊版建立路徑和日後會使用的 CreationExtras
路徑。
這些 CreationExtras
可讓您建構 ViewModelProvider.Factory
,只將您需要的資訊傳遞至每個 ViewModel
,而不需要採用嚴謹的 Factory 子類別階層:
class CustomFactory : ViewModelProvider.Factory {
override fun <T : ViewModel> create(modelClass: Class<T>, extras: CreationExtras): T {
return when (modelClass) {
HomeViewModel::class -> {
// Get the Application object from extras
val application = checkNotNull(extras[ViewModelProvider.AndroidViewModelFactory.APPLICATION_KEY])
// Pass it directly to HomeViewModel
HomeViewModel(application)
}
DetailViewModel::class -> {
// Create a SavedStateHandle for this ViewModel from extras
val savedStateHandle = extras.createSavedStateHandle()
DetailViewModel(savedStateHandle)
}
else -> throw IllegalArgumentException("Unknown class $modelClass")
} as T
}
}
我們只會針對有需要的 ViewModel,在 SavedStateHandleSupport
中使用 CreationExtras
的 createSavedStateHandle()
Kotlin 擴充功能建構 SavedStateHandle
。(Ia6654,b/188541057)
假如想要使用自訂 CreationExtras
,請在您的 ComponentActivity
或 Fragment
中覆寫 getDefaultViewModelCreationExtras()
,這樣該自訂類別就會以輔助插入的內建型態供您的自訂 ViewModelProvider.Factory
使用。如果直接搭配 ViewModelProvider
或是使用 by viewModels()
和 by activityViewModels()
Kotlin 屬性擴充功能,這些額外項目會自動提供給你的自訂工廠 (I79f2b,b/207012584、b/207012585、b/207012490)
修正錯誤
- 修正了為
SavedStateHandle
提供的預設值在程序終止並重建後會再次出現 (即使已特地從SavedStateHandle
中移除亦然) 的問題。這樣一來,SavedStateHandle
就不會再合併預設值和還原值,而只會使用還原值做為可靠資料來源。(I53a4b)
2.4 版
2.4.1 版
2022 年 2 月 9 日
發布 androidx.lifecycle:lifecycle-*:2.4.1
。2.4.1 版包含此連結所列的修訂項目。
修正錯誤
- 從 Lifecycle
2.5.0-alpha01
向後移植:為SavedStateHandle
提供的預設值在程序終止並重建後會再次出現,而且即使已特地從SavedStateHandle
中將其移除亦然。此問題現在已修正,這樣一來,SavedStateHandle
就不會再合併預設值和還原值,而只會使用還原值做為可靠資料來源。(I53a4b) lifecycle-process
現在依附於 AndroidX Startup 1.1.1,當中修正了使用ProcessLifecycleInitializer
時會導致StartupException
的迴歸問題 (b/216490724)
2.4.0 版
2021 年 10 月 27 日
發布了 androidx.lifecycle:lifecycle-*:2.4.0
。2.4.0 版包含此連結所列的修訂項目。
自 2.3.0 版以來的重要異動
- 淘汰了
@OnLifecycleEvent
,請改用LifecycleEventObserver
或DefaultLifecycleObserver
。 - 新增了
androidx.lifecycle:lifecycle-viewmodel-compose
程式庫,當中提供viewModel()
可組合項和LocalViewModelStoreOwner
。- 原始碼破壞性變更:
ViewModelProvider
已使用 Kotlin 重新編寫。ViewModelProvider.Factory.create
方法不再允許使用可設為空值的一般項目。
- 原始碼破壞性變更:
- 為
androidx.lifecycle:lifecycle-runtime-ktx
加入了新的協同程式 API: Lifecycle.repeatOnLifecycle
,這個 API 會在生命週期進入特定狀態或更高階的狀態時,執行協同程式中某區塊的程式碼。隨著生命週期進入與退出目標狀態,該區塊的程式碼也會取消並重新啟動;Flow.flowWithLifecycle
,這個 API 會在生命週期進入特定狀態或更高階的狀態時,從 Flow 上游發送值。DefaultLifecycleObserver
已從lifecycle.lifecycle-common-java8
移至lifecycle.lifecycle-common
。lifecycle.lifecycle-common-java8
無法再提供lifecycle.lifecycle-common
以外的任何其他功能,因此原本依附於該元件的項目可改用lifecycle.lifecycle-common
。lifecycle-viewmodel-ktx
的非協同程式 API 已移至lifecycle-viewmodel
模組。lifecycle-process
現在會使用androidx.startup
進行ProcessLifecycleOwner
初始化。在過去,這是透過
androidx.lifecycle.ProcessLifecycleOwnerInitializer
完成。如果您使用的是
tools:node="remove"
(也就是過去用於初始化程序生命週期的ContentProvider
),則必須改為執行下列操作。<provider android:name="androidx.startup.InitializationProvider" android:authorities=\"${applicationId}.androidx-startup" android:exported="false" tools:node=\"merge"> <!-- If you are using androidx.startup to initialize other components --> <meta-data android:name="androidx.lifecycle.ProcessLifecycleInitializer" android:value="androidx.startup" tools:node="remove" /> </provider>
(或)
<!-- If you want to disable androidx.startup completely. --> <provider android:name="androidx.startup.InitializationProvider" android:authorities="${applicationId}.androidx-startup" tools:node="remove"> </provider>
2.4.0-rc01 版
2021 年 9 月 29 日
發布了 androidx.lifecycle:lifecycle-*:2.4.0-rc01
,且自 Lifecycle 2.4.0-beta01 版以來皆無異動。2.4.0-rc01 版包含此連結所列的修訂項目。
2.4.0-beta01 版
2021 年 9 月 15 日
發布了 androidx.lifecycle:lifecycle-*:2.4.0-beta01
。2.4.0-beta01 版包含此連結所列的修訂項目。
API 變更
- 淘汰了
@OnLifecycleEvent
,請改用LifecycleEventObserver
或DefaultLifecycleObserver
。(I5a8fa) - DefaultLifecycleObserver 已從
androidx.lifecycle.lifecycle-common-java8
移至androidx.lifecycle.lifecycle-common
。androidx.lifecycle.lifecycle-common-java8
無法再提供androidx.lifecycle.lifecycle-common
以外的任何其他功能,因此原本依附於該元件的項目可改用androidx.lifecycle.lifecycle-common
(I021aa) lifecycle-viewmodel-ktx
的非協同程式 API 已移至lifecycle-viewmodel
模組。(I6d5b2)
外部貢獻
2.4.0-alpha03 版
2021 年 8 月 4 日
發布了 androidx.lifecycle:lifecycle-*:2.4.0-alpha03
。2.4.0-alpha03 版包含此連結所列的修訂項目。
API 變更
- 原始碼破壞性變更:ViewModelProvider 已使用 Kotlin 重新編寫。
ViewModelProvider.Factory.create
方法不再允許使用可設為空值的一般項目 (I9b9f6)。
行為變更
- 現在設定重複執行時,一律會依序叫用
Lifecycle.repeatOnLifecycle
:block
(Ibab33)
外部貢獻
- 感謝 chao2zhang 修正
repeatOnLifecycle
說明文件中的程式碼片段。#205。
2.4.0-alpha02 版
2021 年 6 月 16 日
發布了 androidx.lifecycle:lifecycle-*:2.4.0-alpha02
。2.4.0-alpha02 版包含此連結所列的修訂項目。
新功能
- 為
lifecycle-runtime-ktx
新增了一項RepeatOnLifecycleWrongUsage
Lint 檢查功能,可偵測onStart()
或onResume()
中不當使用repeateOnLifecycle
的情況 (706078,b/187887400)
API 變更
- 移除了
LifecycleOwner.addRepeatingJob
API,改為使用Lifecycle.repeatOnLifecycle
,後者遵循結構化並行需求且容易分析。(I4a3a8) - 將
ProcessLifecycleInitializer
設為公開,供其他androidx.startup.Initializer
做為依附元件使用 (I94c31)
修正錯誤
- 修正
NullSafeMutableLiveData
Lint 檢查在欄位含有修飾符時發生的問題 (#147、b/183696616)。 - 修正了
NullSafeMutableLiveData
Lint 檢查功能在程式碼使用一般項目時遇到的另一項問題 (#161,b/184830263)
外部貢獻
- 感謝 maxsav 改善
NullSafeMutableLiveData
Lint 檢查功能。(#147,b/183696616) - 感謝 kozaxinan 改善
NullSafeMutableLiveData
Lint 檢查功能 (#161,b/184830263)
2.4.0-alpha01 版
2021 年 3 月 24 日
發布了 androidx.lifecycle:lifecycle-*:2.4.0-alpha01
。2.4.0-alpha01 版包含此連結所列的修訂項目。
行為變更
lifecycle-process
現在會使用androidx.startup
進行ProcessLifecycleOwner
初始化。在過去,這是透過
androidx.lifecycle.ProcessLifecycleOwnerInitializer
完成。如果您使用的是
tools:node="remove"
(也就是過去用於初始化程序生命週期的ContentProvider
),則必須改為執行下列操作。<provider android:name="androidx.startup.InitializationProvider" android:authorities=\"${applicationId}.androidx-startup" android:exported="false" tools:node=\"merge"> <!-- If you are using androidx.startup to initialize other components --> <meta-data android:name="androidx.lifecycle.ProcessLifecycleInitializer" android:value="androidx.startup" tools:node="remove" /> </provider>
(或)
<!-- If you want to disable androidx.startup completely. --> <provider android:name="androidx.startup.InitializationProvider" android:authorities="${applicationId}.androidx-startup" tools:node="remove"> </provider>
API 變更
- 新增
Flow.flowWithLifecycle
API,這個 API 會在生命週期透過Lifecycle.repeatOnLifecycle
API 進入特定狀態或更高階的狀態時,從上游 Flow 發送值。這是另一種全新LifecycleOwner.addRepeatinJob
API 的替代方法。(I0f4cd)
修正錯誤
- 自 Lifecycle 2.3.1 起:
NonNullableMutableLiveData
Lint 規則現在能夠正確區別「是否可為空值」屬性不同的欄位變數。(b/169249668)
Lifecycle Viewmodel Compose 1.0.0 版
1.0.0-alpha07 版
2021 年 6 月 16 日
發布了 androidx.lifecycle:lifecycle-viewmodel-compose:1.0.0-alpha07
。1.0.0-alpha07 版包含此連結所列的修訂項目。
破壞性 API 變更
viewModel()
現在可接受選用的ViewModelStoreOwner
,以便與LocalViewModelStoreOwner
以外的擁有者合作。舉例來說,您現在可以使用viewModel(navBackStackEntry)
擷取與特定導覽圖相關聯的 ViewModel。(I2628d,b/188693123)
1.0.0-alpha06 版
2021 年 6 月 2 日
發布了 androidx.lifecycle:lifecycle-viewmodel-compose:1.0.0-alpha06
。1.0.0-alpha06 版包含此連結所列的修訂項目。
經更新後支援 Compose 1.0.0-beta08
版。
1.0.0-alpha05 版
2021 年 5 月 18 日
發布了 androidx.lifecycle:lifecycle-viewmodel-compose:1.0.0-alpha05
。1.0.0-alpha05 版包含此連結所列的修訂項目。
新功能
- 經更新後支援 Compose
1.0.0-beta07
版。
修正錯誤
- ui-test-manifest 和 ui-tooling-data 的 AndroidManifest 檔案現在與 Android 12 相容 (I6f9de、b/184718994)
1.0.0-alpha04 版
2021 年 4 月 7 日
發布 androidx.lifecycle:lifecycle-viewmodel-compose:1.0.0-alpha04
。1.0.0-alpha04 版包含此連結所列的修訂項目。
依附元件變更
- 這個版本可讓
androidx.hilt:hilt-navigation-compose
和androidx.navigation:navigation-compose
同步處理androidx.compose.compiler:compiler:1.0.0-beta04
和androidx.compose.runtime:runtime:1.0.0-beta04
依附元件。在 1.0.0 中,編譯器和執行階段必須相符。
1.0.0-alpha03 版
2021 年 3 月 10 日
發布了 androidx.lifecycle:lifecycle-viewmodel-compose:1.0.0-alpha03
。1.0.0-alpha03 版包含此連結所列的修訂項目。
API 變更
LocalViewModelStoreOwner.current
現在會傳回可為空值的ViewModelStoreOwner
,以便更準確地判斷目前組合中是否有可用的ViewModelStoreOwner
。如果 API 須使用ViewModelStoreOwner
(例如viewModel()
和NavHost
),在未設定ViewModelStoreOwner
時仍會擲回例外狀況。(Idf39a)
Lifecycle-Viewmodel-Compose 1.0.0-alpha02 版
2021 年 2 月 24 日
發布了 androidx.lifecycle:lifecycle-viewmodel-compose:1.0.0-alpha02
。1.0.0-alpha02 版包含此連結所列的修訂項目。
API 變更
LocalViewModelStoreOwner
現在有一個可與CompositionLocalProvider
搭配使用的provides
函式,並取代asProvidableCompositionLocal()
API (I45d24)
Lifecycle-Viewmodel-Compose 1.0.0-alpha01 版
2021 年 2 月 10 日
發布 androidx.lifecycle:lifecycle-viewmodel-compose:1.0.0-alpha01
。1.0.0-alpha01 版包含此連結所列的修訂項目。
新功能
viewModel()
可組合項和LocalViewModelStoreOwner
已從androidx.compose.ui.viewinterop
移至androidx.lifecycle.viewmodel.compose
套件中的這個構件 (I7a374)
2.3.1 版
Lifecycle 2.3.1 版
2021 年 3 月 24 日
發布了 androidx.lifecycle:lifecycle-*:2.3.1
。2.3.1 版包含此連結所列的修訂項目。
修正錯誤
NonNullableMutableLiveData
Lint 規則現在能夠正確區別「是否可為空值」屬性不同的欄位變數。(b/169249668)
2.3.0 版
2.3.0 版
2021 年 2 月 10 日
發布了 androidx.lifecycle:lifecycle-*:2.3.0
。2.3.0 版包含此連結所列的修訂項目。
自 2.2.0 版以來的重大異動
SavedStateHandle
支援非 Parcelable 類別:SavedStateHandle
現在支援延遲序列化,做法是讓您針對特定鍵呼叫setSavedStateProvider()
,這樣就能在系統要求SavedStateHandle
儲存其狀態時,提供可回呼saveState()
的SavedStateProvider
。請參閱儲存無法剖析的類別。- Lifecycle 行為強制執行:
- LifecycleRegistry 現在會強制將
DESTROYED
設為最終狀態。 LifecycleRegistry
現在會確認其方法是透過主執行緒呼叫。這一向是活動、片段等元件生命週期的必要規定。要是從非主執行緒加入觀測工具,就會導致執行階段發生難以偵測的異常終止情況。針對隸屬於您自有元件的LifecycleRegistry
物件,您可以使用LifecycleRegistry.createUnsafe(...)
明確地停用檢查功能,但這樣一來,您就必須確保有適當的同步處理機制,以因應透過不同執行緒存取這個LifecycleRegistry
的情況。
- LifecycleRegistry 現在會強制將
- 生命週期狀態和事件輔助方法:為
Lifecycle.Event
新增了downFrom(State)
、downTo(State)
、upFrom(State)
、upTo(State)
的靜態輔助方法,以便依據指定State
和轉換方向產生Event
。新增了getTargetState()
方法,該方法會提供 Lifecycle 在Event
結束後的直接轉換目標State
。 withStateAtLeast
:新增了Lifecycle.withStateAtLeast
API,等待生命週期達到特定狀態,並在狀態改變的時間點同步執行非暫停程式碼區塊,然後繼續執行結果。這些 API 與現有的when*
方法不同,並不允許執行暫停程式碼,也不使用自訂調度工具。(aosp/1326081)ViewTree
API:全新的ViewTreeLifecycleOwner.get(View)
和ViewTreeViewModelStoreOwner.get(View)
API,可讓您依據View
執行個體,分別擷取其所屬的LifecycleOwner
和ViewModelStoreOwner
。您必須升級至 Activity1.2.0
和 Fragment1.3.0
,以及 AppCompat 1.3.0-alpha01 以上版本,才能正確填入這項資訊。findViewTreeLifecycleOwner
和findViewTreeViewModelStoreOwner
Kotlin 擴充功能可分別透過lifecycle-runtime-ktx
和lifecycle-viewmodel-ktx
使用。- 淘汰
LiveData.observe()
Kotlin 擴充功能:使用 lambda 語法時所需的LiveData.observe()
Kotlin 擴充功能現已淘汰,這是因為使用 Kotlin 1.4 時不需用到該擴充功能。
2.3.0-rc01 版
2020 年 12 月 16 日
發布了 androidx.lifecycle:lifecycle-*:2.3.0-rc01
。2.3.0-rc01 版包含此連結所列的修訂項目。
修正錯誤
SavedStateHandle
的keys()
方法現在於狀態儲存前後皆會維持一致;該方法現在除了包括在set()
和getLiveData()
中所使用的鍵,也納入了先前在setSavedStateProvider()
中所使用的鍵 (aosp/1517919,b/174713653)
外部貢獻
- 用於暫停生命週期感知協同程式的 API 現在能夠更妥善地處理對
yield()
的呼叫。感謝 Nicklas Ansman Giertz!(aosp/1430830,b/168777346)
2.3.0-beta01 版
2020 年 10 月 1 日
發布了 androidx.lifecycle:lifecycle-*:2.3.0-beta01
。2.3.0-beta01 版包含此連結所列的修訂項目。
API 變更
- 使用 lambda 語法時所需的
LiveData.observe()
Kotlin 擴充功能現已淘汰,這是因為使用 Kotlin 1.4 時不需用到該擴充功能。(I40d3f)
修正錯誤
- 升級 AndroidX 以使用 Kotlin 1.4 (Id6471,b/165307851、b/165300826)
說明文件變更
- 更新了
liveData
建構工具和asLiveData()
文件,加入有關變更指定逾時值的詳細資訊。(aosp/1122324)
2.3.0-alpha07 版
2020 年 8 月 19 日
發布了 androidx.lifecycle:lifecycle-*:2.3.0-alpha07
。2.3.0-alpha07 版包含此連結所列的修訂項目。
修正錯誤
- 修正了
NullSafeMutableLiveData
Lint 檢查功能中的異常終止問題 (aosp/1395367)
2.3.0-alpha06 版
2020 年 7 月 22 日
發布了 androidx.lifecycle:lifecycle-*:2.3.0-alpha06
。2.3.0-alpha06 版包含此連結所列的修訂項目。
新功能
- 為
Lifecycle.Event
新增了downFrom(State)
、downTo(State)
、upFrom(State)
、upTo(State)
的靜態輔助方法,以便依據指定State
和轉換方向產生Event
。新增了getTargetState()
方法,該方法會提供 Lifecycle 在Event
結束後的直接轉換目標State
。(I00887) - 新增了
Lifecycle.withStateAtLeast
API,等待生命週期達到特定狀態,並在狀態改變的時間點同步執行非暫停程式碼區塊,然後繼續執行結果。這些 API 與現有的when*
方法不同,並不允許執行暫停程式碼,也不使用自訂調度工具。(aosp/1326081)
行為變更
- LifecycleRegistry 現在會強制將
DESTROYED
設為最終狀態。(I00887) LifecycleRegistry
現在會確認其方法是透過主執行緒呼叫。這一向是活動、片段等元件生命週期的必要規定。要是從非主執行緒加入觀測工具,就會導致執行階段發生難以偵測的異常終止情況。針對隸屬於您自有元件的LifecycleRegistry
物件,您可以使用LifecycleRegistry.createUnsafe(...)
明確地停用檢查功能,但這樣一來,您就必須確保有適當的同步處理機制,以因應透過不同執行緒存取這個LifecycleRegistry
的情況。(Ie7280,b/137392809)
修正錯誤
- 修正了
NullSafeMutableLiveData
中的異常終止問題 (b/159987480) - 修正了
lifecycle-livedata-core-ktx
(特別是NullSafeMutableLiveData
) 隨附的 Lint 檢查功能ObsoleteLintCustomCheck
(b/158699265)。
2.3.0-alpha05 版
2020 年 6 月 24 日
發布了 androidx.lifecycle:lifecycle-*:2.3.0-alpha05
。2.3.0-alpha05 版包含此連結所列的修訂項目。
修正錯誤
LiveData
現在能夠更妥善地處理對重新進入案例,避免重複呼叫onActive()
或onInactive()
(b/157840298)- 修正了 Lint 檢查功能在 Android Studio 4.1 Canary 6 以上版本中無法執行的問題 (aosp/1331903)
2.3.0-alpha04 版
2020 年 6 月 10 日
發布了 androidx.lifecycle:lifecycle-*:2.3.0-alpha04
。2.3.0-alpha04 版包含此連結所列的修訂項目。
修正錯誤
- 修正了
NonNullableMutableLiveData
Lint 檢查中的異常終止問題 (b/157294666) - 針對採用非空值類參數的
MutableLiveData
設定了null
值的案例,NonNullableMutableLiveData
Lint 檢查功能現在的涵蓋量大幅提升。(b/156002218)
2.3.0-alpha03 版
2020 年 5 月 20 日
發布了 androidx.lifecycle:lifecycle-*:2.3.0-alpha03
。2.3.0-alpha03 版包含此連結所列的修訂項目。
新功能
SavedStateHandle
現在支援延遲序列化,做法是讓您針對特定鍵呼叫setSavedStateProvider()
,這樣就能在系統要求SavedStateHandle
儲存其狀態時,提供可回呼saveState()
的SavedStateProvider
。(b/155106862)- 全新的
ViewTreeViewModelStoreOwner.get(View)
API 可讓您依據ViewModelStoreOwner
執行個體,擷取其所屬的View
。您必須升級至 Activity1.2.0-alpha05
、Fragment1.3.0-alpha05
和 AppCompat1.3.0-alpha01
,才能正確填入這項資訊。在lifecycle-viewmodel-ktx
中新增了findViewModelStoreOwner()
Kotlin 擴充功能。(aosp/1295522)
修正錯誤
- 修正了一項導致 Lifecycle
2.3.0-alpha01
中推出的MutableLiveData
Lint 檢查功能無法與lifecycle-livedata-core-ktx
構件一起發布的問題 (b/155323109)
2.3.0-alpha02 版
2020 年 4 月 29 日
發布了 androidx.lifecycle:lifecycle-*:2.3.0-alpha02
。2.3.0-alpha02 版包含此連結所列的修訂項目。
API 變更
SavedStateViewModelFactory
現在可讓您將空值Application
傳遞至其建構函式,針對目前沒有應用程式且不需用到AndroidViewModel
支援的案例提供更完善的支援。(aosp/1285740)
修正錯誤
- 防止 API 28 以下的裝置發生類別驗證失敗的情況,藉此提高冷啟動成效。(aosp/1282118)
2.3.0-alpha01 版
2020 年 3 月 4 日
發布了 androidx.lifecycle:lifecycle-*:2.3.0-alpha01
。2.3.0-alpha01 版包含此連結所列的修訂項目。
新功能
- 全新的
ViewTreeLifecycleOwner.get(View)
API 可讓您依據LifecycleOwner
執行個體,擷取其所屬的View
。您必須升級至 Activity1.2.0-alpha01
和 Fragment1.3.0-alpha01
,才能正確填入這項資訊。您可以透過lifecycle-runtime-ktx
使用findViewTreeLifecycleOwner
Kotlin 擴充功能。(aosp/1182361、aosp/1182956) - 新增了一項 Lint 檢查功能,可在您為 Kotlin 中定義為非空值的
MutableLiveData
設定null
值時發出警告。這項檢查功能會在您使用livedata-core-ktx
或livedata-ktx
構件時提供。(aosp/1154723、aosp/1159092) - 推出了新的
lifecycle-runtime-testing
構件,其提供的TestLifecycleOwner
會導入LifecycleOwner
並提供執行緒安全的可變動Lifecycle
。(aosp/1242438)
修正錯誤
lifecycle-runtime
構件現在擁有專屬的套件名稱。(aosp/1187196)
2.2.0 版
ViewModel-Savedstate 2.2.0 版
2020 年 2 月 5 日
發布了 androidx.lifecycle:lifecycle-viewmodel-savedstate:2.2.0
。2.2.0 版包含此連結所列的修訂項目。
Lifecycle ViewModel SavedState 現在與其他 Lifecycle 構件使用同一個版本。2.2.0
的行為與 1.0.0
的行為完全相同。
2.2.0 版
2020 年 1 月 22 日
發布了 androidx.lifecycle:lifecycle-*:2.2.0
。2.2.0 版包含此連結所列的修訂項目。
自 2.1.0 版以來的重要變更
- Lifecycle 協同程式整合:新的
lifecycle-runtime-ktx
構件能夠將 Lifecycle 與 Kotlin 協同程式進行整合。lifecycle-livedata-ktx
也經由拓展妥善運用協同程式的優勢。詳情請參閱使用 Kotlin 協同程式搭配架構元件一文。 - 淘汰
ViewModelProviders.of()
:已淘汰ViewModelProviders.of()
。使用 Fragment1.2.0
時,您可以將Fragment
或FragmentActivity
傳遞至新的ViewModelProvider(ViewModelStoreOwner)
建構函式,以達到相同作用。 - 淘汰
lifecycle-extensions
構件:隨著上述ViewModelProviders.of()
的淘汰,這個版本也淘汰了lifecycle-extensions
中的最後一個 API,這個構件現應視作完全淘汰。我們強烈建議將依附元件設為您需要的特定 Lifecycle 構件 (例如,使用LifecycleService
時請依附於lifecycle-service
;使用ProcessLifecycleOwner
時則依附於lifecycle-process
),而不要使用lifecycle-extensions
,原因是lifecycle-extensions
日後並不會推出2.3.0
版。 - Gradle 遞增註解處理工具:根據預設,Lifecycle 的註解處理工具為遞增模式。如果應用程式是以 Java 8 程式設計語言編寫,您可以改用
DefautLifecycleObserver
;如果是以 Java 7 程式設計語言編寫,則可以使用LifecycleEventObserver
。
2.2.0-rc03 版
2019 年 12 月 4 日
發布了 androidx.lifecycle:lifecycle-*:2.2.0-rc03
。查看 2.2.0-rc03 版的修訂項。
修正錯誤
- 修正了儲存在
ViewModelStore
中的模擬ViewModel
後來經由預設工廠查詢調用時出現的失敗錯誤。 - 修正了
Dispatchers.Main.immediate
在相應的生命週期事件期間,於launchWhenCreated
和類似方法中同時遭到呼叫的使用方式 (aosp/1156203)
外部貢獻
- 感謝 Anders Järleberg 協助修正問題!(aosp/1156203)
- 感謝 Jetbrains 的 Vsevolod Tolstopyatov 審查內嵌執行作業的導入結果。
依附元件變更
- Lifecycle 擴充功能現在依附於 Fragment
1.2.0-rc03
。
2.2.0-rc02 版
2019 年 11 月 7 日
發布了 androidx.lifecycle:lifecycle-*:2.2.0-rc02
。2.2.0-rc02 版包含此連結所列的修訂項目。
修正錯誤
- 修正了程式庫 ProGuard 設定中的錯誤;受到該錯誤影響的裝置為目標 API 級別在 29 以下,但搭載的 API 級別在 28 以上的裝置。(b/142778206)
2.2.0-rc01 版
2019 年 10 月 23 日
發布了 androidx.lifecycle:lifecycle-*:2.2.0-rc01
。2.2.0-rc01 版包含此連結所列的修訂項目。
修正錯誤
- 修正了
launchWhenCreated
和相關方法因使用Dispatchers.Main
(而非Dispatchers.Main.immediate
),導致執行時間比相關聯的 Lifecycle 方法晚一拍的問題。(aosp/1145596)
外部貢獻
- 感謝 Nicklas Ansman 協助修正問題!(aosp/1145596)
2.2.0-beta01 版
2019 年 10 月 9 日
發布了 androidx.lifecycle:lifecycle-*:2.2.0-beta01
。2.2.0-beta01 版包含此連結所列的修訂項目。
修正錯誤
- 修正了 Lifecycle 2.2.0-alpha05 中對
ProcessLifecycleOwner
排序造成影響,導致活動的LifecycleOwner
在 Android 10 裝置上移至已啟動與已恢復狀態的迴歸問題。(aosp/1128132) - 修正了 Lifecycle
2.2.0-alpha05
中引起的迴歸問題;在使用lifecycle-process
的2.0.0
或2.1.0
版時,該問題會導致NullPointerException
(b/141536990)
2.2.0-alpha05 版
2019 年 9 月 18 日
發布了 androidx.lifecycle:lifecycle-*:2.2.0-alpha05
。2.2.0-alpha05 版包含此連結所列的修訂項目。
修正錯誤
- 修正協同程式即時資料建構工具中的競爭狀況。b/140249349
2.2.0-alpha04 版
2019 年 9 月 5 日
發布了 androidx.lifecycle:lifecycle-*:2.2.0-alpha04
。您可以前往這裡查看這個版本包含的修訂項目。
新功能
lifecycleScope
、whenCreated
、whenStarted
、whenResumed
、viewModelScope
和liveData
的基礎實作現在均使用Dispatchers.Main.immediate
,而非Dispatchers.Main
(b/139740492)
外部貢獻
- 感謝 Nicklas Ansman 協助遷移至
Dispatchers.Main.immediate
!(aosp/1106073)
2.2.0-alpha03 版
2019 年 8 月 7 日
發布 androidx.lifecycle:lifecycle-*:2.2.0-alpha03
。您可以前往這裡查看這個版本包含的修訂項目。
新功能
ViewModelStoreOwner
的實作現在可選擇導入HasDefaultViewModelProviderFactory
,以提供預設的ViewModelProvider.Factory
。Activity1.1.0-alpha02
、Fragment1.2.0-alpha02
和 Navigation2.2.0-alpha01
都已採用這種做法。(aosp/1092370,b/135716331)
API 變更
- 淘汰了
ViewModelProviders.of()
。您可以將Fragment
或FragmentActivity
傳遞至新的ViewModelProvider(ViewModelStoreOwner)
建構函式,以達到相同作用 (aosp/1009889)
2.2.0-alpha02 版
2019 年 7 月 2 日
發布 androidx.lifecycle:*:2.2.0-alpha02
。您可以前往這裡查看這個版本包含的修訂項目。
API 變更
- 將
LiveDataScope.initialValue
替換成了LiveDataScope.latestValue
,可追蹤liveData
區塊目前發送的值。 - 為
liveData
建構工具新增超載,此工具會以Duration
類型接收timeout
參數。
2.2.0-alpha01 版
2019 年 5 月 7 日
發布了 androidx.lifecycle:*:2.2.0-alpha01
。您可以前往這裡查看這個版本包含的修訂項目。
新功能
- 這個版本新增多項功能,可為 Lifecycle 和 LiveData 提供 Kotlin 協同程式支援。相關詳細說明文件,請前往這裡。
ViewModel-SavedState 1.0.0 版
1.0.0 版
2020 年 1 月 22 日
發布了 androidx.lifecycle:lifecycle-viewmodel-savedstate:1.0.0
。1.0.0 版包含此連結所列的修訂項目。
1.0.0 版中的重要功能
- 新增了 SavedStateHandle 類別。這可讓
ViewModel
類別存取已儲存的狀態並提供相關資訊。這個物件可透過ViewModel
類別的建構函式接收,而 Fragments 和 AppCompatActivity 預設提供的工廠會自動植入SavedStateHandle
。 - 新增了 AbstractSavedStateViewModelFactory,可讓您為
ViewModel
建立自訂工廠,並授權其存取SavedStateHandle
。
ViewModel-Savedstate 1.0.0-rc03 版
2019 年 12 月 4 日
發布了 androidx.lifecycle:lifecycle-viewmodel-savedstate:1.0.0-rc03
。1.0.0-rc03 版包含此連結所列的修訂項目。
依附元件變更
- Lifecycle ViewModel SavedState 現在依附於 Lifecycle
2.2.0-rc03
。
Viewmodel-Savedstate 1.0.0-rc02 版
2019 年 11 月 7 日
發布了 androidx.lifecycle:lifecycle-viewmodel-savedstate:1.0.0-rc02
。1.0.0-rc02 版包含此連結所列的修訂項目。
依附元件變更
- 現在依附於 Lifecycle
2.2.0-rc02
。
ViewModel-SavedState 1.0.0-rc01 版
2019 年 10 月 23 日
發布了 androidx.lifecycle:lifecycle-viewmodel-savedstate:1.0.0-rc01
,且自 1.0.0-beta01
版以來皆無異動。1.0.0-rc01 版包含此連結所列的修訂項目。
ViewModel-Savedstate 1.0.0-beta01 版
2019 年 10 月 9 日
發布了 androidx.lifecycle:lifecycle-viewmodel-savedstate:1.0.0-beta01
。1.0.0-beta01 版包含此連結所列的修訂項目。
修正錯誤
- 修正了在
Activity.onActivityResult()
中首次存取 SavedState ViewModel 時會導致IllegalStateException
的問題。(b/139093676) - 修正了使用
AbstractSavedStateViewModelFactory
時發生的IllegalStateException
(b/141225984)
ViewModel-SavedState 1.0.0-alpha05 版
2019 年 9 月 18 日
發布了 androidx.lifecycle:lifecycle-viewmodel-savedstate:1.0.0-alpha05
。1.0.0-alpha05 版包含此連結所列的修訂項目。
API 變更
SavedStateViewModelFactory
不會再擴充AbstractSavedStateViewModelFactory
,且 API 只會為提出要求的 ViewModel 建立SavedStateHandle
(aosp/1113593)
ViewModel-SavedState 1.0.0-alpha03 版
2019 年 8 月 7 日
發布 androidx.lifecycle:lifecycle-viewmodel-savedstate:1.0.0-alpha03
。您可以前往這裡查看這個版本包含的修訂項目。
破壞性變更
lifecycle-viewmodel-savedstate
不再依附於fragment
,相關的SavedStateViewModelFactory(Fragment)
和SavedStateViewModelFactory(FragmentActivity)
建構函式皆已移除。現在,改由SavedStateViewModelFactory
做為 Activity1.1.0-alpha02
、Fragment1.2.0-alpha02
和 Navigation2.2.0-alpha01
的預設工廠。(b/135716331)
ViewModel-SavedState 1.0.0-alpha02 版
2019 年 7 月 2 日
發布 androidx.lifecycle:lifecycle-viewmodel-savedstate:1.0.0-alpha02
。您可以前往這裡查看這個版本包含的修訂項目。
新功能
- 新增了可接受預設值的
SavedStateHandle.getLiveData()
多載。
API 變更
SavedStateVMFactory
已重新命名為SavedStateViewModelFactory
。AbstractSavedStateVMFactory
已重新命名為AbstractSavedStateViewModelFactory
。
ViewModel-Savedstate 1.0.0-alpha01 版
2019 年 3 月 13 日
發布了 androidx.lifecycle:lifecycle-viewmodel-savedstate:1.0.0-alpha01
。您可以前往這裡查看這個初始版本的完整修訂版本記錄。
新功能
ViewModels
現在可為 savedstate 提供相關資訊。如果要這麼做,請使用新推出的 ViewModel 工廠SavedStateVMFactory
,並確保您的 ViewModel 有一個可透過參數接收SavedStateHandle
物件的建構函式。
2.1.0 版
自 2.0.0 版以來的重要異動
- 新增了
LifecycleEventObserver
,適用於需要生命週期事件串流的案例。這是公用 API,而非隱藏的GenericLifecycleObserver
類別。 - 新增了適用於
LiveData.observe
方法和Transformations.*
方法的 ktx 擴充功能。 - 新增了
Transformations.distinctUntilChanged
,其建立的新 LiveData 物件會等到來源LiveData
的值出現變更時才發送值。 - 新增了擴充功能屬性
ViewModel.viewModelScope
,在 ViewModel 中提供協同程式支援。
2.1.0 版
2019 年 9 月 5 日
發布了 androidx.lifecycle:lifecycle-*:2.1.0
。您可以前往這裡查看這個版本包含的修訂項目。
2.1.0-rc01 版
2019 年 7 月 2 日
發布了 androidx.lifecycle:*:2.1.0-rc01
,且自 androidx.lifecycle:*:2.1.0-beta01
版以來皆無異動。您可以前往這裡查看這個版本包含的修訂項目。
2.1.0-beta01 版
2019 年 5 月 7 日
發布了 androidx.lifecycle:*:2.1.0-beta01
。您可以前往這裡查看這個版本包含的修訂項目。
新功能
- Lifecycle 升級至 Beta 版:過往 Alpha 版中推出的 API 皆已進入穩定狀態,因此會維持不變,包括用於轉換與觀測的
liveData
擴充功能函式、採用屬性委派的ViewModel
初始化等等。
2.1.0-alpha04 版
2019 年 4 月 3 日
發布 androidx.lifecycle:*:2.1.0-alpha04
。您可以前往這裡查看這個版本包含的修訂項目。
API 變更
- 破壞性變更:
by viewModels()
和by activityViewModels()
的基礎 API 已改為直接支援ViewModelStore
,而不只是ViewModelStoreOwner
。(aosp/932932)
2.1.0-alpha03 版
2019 年 3 月 13 日
發布了 androidx.lifecycle:*:2.1.0-alpha03
。您可以前往這裡查看這個版本包含的修訂項目完整清單。
API 變更
- 移除了
ViewModelProvider.KeyedFactory
。ViewModelProvider.Factory
以外的第二個介面無法在 Kotlinby viewmodels {}
中透過屬性委派與新功能妥善組合。(aosp/914133)
2.1.0-alpha02 版
2019 年 1 月 30 日
發布了 androidx.lifecycle 2.1.0-alpha02
。
API 變更
LifecycleRegistry
現在包含setCurrentState()
方法,用於取代目前已淘汰的setState()
方法。(aosp/880715)
修正錯誤
- 修正了模擬
ViewModel
執行個體在所屬的ViewModelStore
遭到清除時會異常終止的問題。b/122273087
2.1.0-alpha01 版
2018 年 12 月 17 日
發布了 androidx.lifecycle 2.1.0-alpha01
。
新功能
- 新增了
LifecycleEventObserver
,適用於需要生命週期事件串流的案例。這是公用 API,而非隱藏的GenericLifecycleObserver
類別。 - 新增了適用於
LiveData.observe
方法和Transformations.*
方法的 ktx 擴充功能。 - 新增了
Transformations.distinctUntilChanged
方法,其建立的新LiveData
物件會等到來源 LiveData 的值出現變更時才發送值。 - 在 ViewModel 中提供協同程式支援:新增了擴充功能屬性
ViewModel.viewModelScope
。 - 新增
ViewModelProvider.KeyedFactory
,這是適用於 ViewModel 的工廠,可接收create
方法中的key
和Class
。
2.0.0 版
2.0.0 版
2018 年 9 月 21 日
Lifecycle 2.0.0
發布,修正 ViewModel 中 2.0.0-rc01
的一項錯誤。
修正錯誤
- 修正了錯誤移除建構函式的 ViewModel ProGuard 規則 (b/112230489)
2.0.0-beta01 版
2018 年 7 月 2 日
修正錯誤
- 修正了 LifecycleObserver ProGuard 規則,僅保留實作項目,不保留子介面 (b/71389427)
- 修正 ViewModel ProGuard 規則,允許模糊處理與縮減作業
AndroidX 之前的版本
針對 AndroidX 之前的 Lifecycle 版本 (如下所示),請加入下列依附元件:
dependencies {
def lifecycle_version = "1.1.1"
// ViewModel and LiveData
implementation "android.arch.lifecycle:extensions:$lifecycle_version"
// alternatively - just ViewModel
implementation "android.arch.lifecycle:viewmodel:$lifecycle_version" // For Kotlin use viewmodel-ktx
// alternatively - just LiveData
implementation "android.arch.lifecycle:livedata:$lifecycle_version"
// alternatively - Lifecycles only (no ViewModel or LiveData).
// Support library depends on this lightweight import
implementation "android.arch.lifecycle:runtime:$lifecycle_version"
annotationProcessor "android.arch.lifecycle:compiler:$lifecycle_version" // For Kotlin use kapt instead of annotationProcessor
// alternately - if using Java8, use the following instead of compiler
implementation "android.arch.lifecycle:common-java8:$lifecycle_version"
// optional - ReactiveStreams support for LiveData
implementation "android.arch.lifecycle:reactivestreams:$lifecycle_version"
// optional - Test helpers for LiveData
testImplementation "android.arch.core:core-testing:$lifecycle_version"
}
1.1.1 版
2018 年 3 月 21 日
只有一項小幅異動:android.arch.core.util.Function
從 arch:runtime
移至 arch:common
。這樣一來,即使沒有執行階段依附元件,也能使用該函式,例如在下方的 paging:common
中使用。
lifecycle:common
是 lifecycle:runtime
的依附元件,因此這項變更不會直接影響 lifecycle:runtime
,只會影響 Paging 等直接依附於 lifecycle:common
的模組。
1.1.0 版
2018 年 1 月 22 日
包裝變更
現在提供縮小許多的新型依附元件:
android.arch.lifecycle:livedata:1.1.0
android.arch.lifecycle:viewmodel:1.1.0
API 變更
- 現在移除了已淘汰的
LifecycleActivity
和LifecycleFragment
,請改用FragmentActivity
、AppCompatActivity
或支援Fragment
。 - 為
ViewModelProviders
和ViewModelStores
新增了@NonNull
註解。 - 淘汰了
ViewModelProviders
建構函式,請直接改用其靜態方法。 - 淘汰了
ViewModelProviders.DefaultFactory
,請改用ViewModelProvider.AndroidViewModelFactory
。 - 新增靜態的
ViewModelProvider.AndroidViewModelFactory.getInstance(Application)
方法,擷取適合用於建立ViewModel
和AndroidViewModel
執行個體的靜態Factory
。