生命週期

生命週期感知元件會根據其他元件的生命週期狀態變化 (例如活動和片段)，採取因應的動作。這些元件有助於產生更井然有序且通常更精簡的程式碼，維護起來更輕鬆。

下表列出了 androidx.lifecycle 群組中的所有構件。

構件 穩定版 候選版 Beta 版 Alpha 版
lifecycle-* 2.9.2 - - -
lifecycle-viewmodel-navigation3 - - - 1.0.0-alpha03
本程式庫上次更新日期：2025 年 7 月 16 日

宣告依附元件

如果要為 Lifecycle 新增依附元件，您必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。

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

Kotlin

Groovy

    dependencies {
        def lifecycle_version = "2.9.2"
        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"

        // ViewModel integration with Navigation3
        implementation "androidx.lifecycle:lifecycle-viewmodel-navigation3:1.0.0-alpha03"

        // 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.9.2"
        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")

        // ViewModel integration with Navigation3
        implementation("androidx.lifecycle:lifecycle-viewmodel-navigation3:1.0.0-alpha03")

        // 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.9.2"
        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.9.2"
        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 說明文件。

Lifecycle ViewModel Navigation3 1.0.0 版

1.0.0-alpha03 版本

2025 年 7 月 2 日

發布 androidx.lifecycle:lifecycle-viewmodel-navigation3:1.0.0-alpha03 和 androidx.lifecycle:lifecycle-viewmodel-navigation3-android:1.0.0-alpha03。1.0.0-alpha03 版包含這些修訂項目。

依附元件變更

1.0.0-alpha02 版

2025 年 6 月 18 日

發布 androidx.lifecycle:lifecycle-viewmodel-navigation3:1.0.0-alpha02 和 androidx.lifecycle:lifecycle-viewmodel-navigation3-android:1.0.0-alpha02。1.0.0-alpha02 版包含這些修訂項目。

依附元件更新

1.0.0-alpha01 版

2025 年 5 月 23 日

發布 androidx.lifecycle:lifecycle-viewmodel-navigation3:1.0.0-alpha01。1.0.0-alpha01 版包含這些修訂項目。

新功能

  • Lifecycle ViewModel Navigation3 是與 Navigation3 一併建構的新程式庫，可與 ViewModels 整合。androidx.lifecycle:lifecycle-viewmodel-navigation3 構件提供 ViewModelStoreNavEntryDecorator，而 ViewModelStoreNavEntryDecorator 則為每個 NavEntry 的內容提供專屬 ViewModelStoreOwner。此外，它還提供 rememberViewModelStoreNavEntryDecorator()，確保裝飾器能正確處理設定變更。
val viewModelDecorator = rememberViewModelStoreNavEntryDecorator()

NavDisplay(
  …,
  entryDecorators =
  listOf(
    rememberSceneSetupNavEntryDecorator(),
    rememberSavedStateNavEntryDecorator(),
    viewModelDecorator
  )
)

2.9 版

2.9.2 版

2025 年 7 月 16 日

發布 androidx.lifecycle:lifecycle-*:2.9.2。2.9.2 版包含這些修訂項目。

修正錯誤

  • 在 Lifecycle 構件中新增 Kotlin Multiplatform (KMP) 目標。Lifecycle 現在支援下列平台：JVM (Android 和電腦)、原生 (Linux、iOS、watchOS、macOS、MinGW) 和網頁 (JavaScript、WasmJS)。請注意，由於這項功能需要 Compose 1.9 穩定版，因此 *-compose 構件中不會新增任何 KMP 目標。(I01cb8)。

依附元件更新

2.9.1 版

2025 年 6 月 4 日

發布 androidx.lifecycle:lifecycle-*:2.9.1。2.9.1 版包含這些修訂項目。

修正錯誤

  • 修正 SavedStateHandle.remove(key) 未清除 SavedStateHandle.getMutableStateFlow(key) 狀態的問題。(d5f939、b/418746333)

2.9.0 版

2025 年 5 月 7 日

發布 androidx.lifecycle:lifecycle-*:2.9.0。2.9.0 版包含這些修訂項目。

自 2.8.0 版以來的重要異動

  • 我們提供新的 androidx.lifecycle:lifecycle-viewmodel-testing KMP 構件，其中包含 ViewModelScenario 類別，可測試隔離狀態的 ViewModels，並支援 onCleared 和 SavedStateHandle，以及透過 recreate() 測試程序終止和重新建立。
  • 在 SavedStateHandle 中新增 getMutableStateFlow，傳回 MutableStateFlow。這項新功能僅適用於按鍵，無法與 getLiveData 搭配使用。如果您嘗試使用這兩者存取相同狀態，系統會擲回例外狀況。
  • CreationExtras 現在包含類似對應的運算子超載，可讓您以慣用的 Kotlin 語言操作內容。可搭配 CreationExtras 使用 in、+= 和 +。

KotlinX 序列化支援

  • 我們在 SavedState 1.3.0 中新增了 KotlinX 序列化支援，並導入 saved (延遲屬性委派)，方便您在 SavedStateHandle 中儲存 @Serializable 類別，並在程序終止及重建時自動還原這些類別。請注意，saved 委派項是延遲的，在存取前不會呼叫 init lambda 或將任何內容儲存至 SavedStateHandle。

    @Serializable
data class Person(val firstName: String, val lastName: String)

class MyViewModel(handle: SavedStateHandle) : ViewModel() {
    var person by handle.saved { Person("John", "Doe") }

    fun onPersonChanged(person: Person) {
        this.person = person
    }
}

Kotlin Multiplatform

  • lifecycle-testing 模組現在與 KMP 相容，包括 TestLifecycleOwner 等 API。
  • lifecycle-viewmodel-savedstate 模組現在與 KMP 相容，包括 SavedStateHandle 等 API。
  • 「androidx.compose.ui.platform.LocalLifecycleOwner」現已在常見來源集推出。
  • NewInstanceFactory 現已支援 JVM 電腦和 Android 目標。

行為變更

  • Lifecycle.DESTROYED 狀態為終端狀態，現在嘗試將 Lifecycle 從這個狀態移至任何其他狀態，都會導致 IllegalStateException。
  • 如果傳回的 Bundle 為空，SavedStateHandle 就不會再包含任何 SavedStateProvider.saveState()。

2.9.0-rc01 版

2025 年 4 月 23 日

發布 androidx.lifecycle:lifecycle-*:2.9.0-rc01。2.9.0-rc01 版包含這些修訂項目。

2.9.0-beta01 版

2025 年 4 月 9 日

發布 androidx.lifecycle:lifecycle-*:2.9.0-beta01。2.9.0-beta01 版包含這些修訂項目。

API 變更

  • Lifecycle ViewModel Compose 現在與 Compose Runtime 1.7.1 以上版本使用相同的 Kotlin Multiplatform 設定，因此已移除 -desktop 構件，並新增 -jvmStubs 和 -linuxx64Stubs 構件。這些目標都不會使用，只是為了協助 Jetbrains Compose 而設的預留位置。(I5cb14、b/406592090)

依附元件更新

  • 這個程式庫現在指定 Kotlin 2.0 語言層級，且需要 KGP 2.0.0 以上版本。(Idb6b5)
  • Lifecycle ViewModel Compose 現在依附於 Compose 1.7.8。(I5cb14、b/406592090)

2.9.0-alpha13 版

2025 年 3 月 26 日

「androidx.lifecycle:lifecycle-*:2.9.0-alpha13」已發布，沒有重大公開異動。2.9.0-alpha13 版包含這些修訂項目。

2.9.0-alpha12 版

2025 年 3 月 12 日

發布 androidx.lifecycle:lifecycle-*:2.9.0-alpha12。2.9.0-alpha12 版包含這些修訂項目。

API 變更

  • 在所有支援的 KMP 平台中，將 @MainThread 註解新增至 ViewModelProvider.get。(I7e8dd、b/397736115)
  • 將 SavedState*Delegates 重新命名為 SavedState*Delegate。(I8589b、b/399629301)

2.9.0-alpha11 版

2025 年 2 月 26 日

發布 androidx.lifecycle:lifecycle-*:2.9.0-alpha11。2.9.0-alpha11 版包含這些修訂項目。

API 變更

  • 將 SavedStateConfig 參數新增至 saved() 委派 (I39b3a)

2.9.0-alpha10 版

2025 年 2 月 12 日

發布 androidx.lifecycle:lifecycle-*:2.9.0-alpha10。2.9.0-alpha10 版包含這些修訂版本。

API 變更

  • 將 MutableStateSerializer 從 lifecycle-viewmodel-compose 移至 savedstate-compose。(I4f690、b/378895074)

外部貢獻

  • 新增 Lint 問題，用於在組合中呼叫 Lifecycle::currentState，並建議使用 currentStateAsalue().value，確保生命週期狀態的變更會正確導致重組。感謝 Steven Schoen！(Iad484)

2.9.0-alpha09 版

2025 年 1 月 29 日

發布 androidx.lifecycle:lifecycle-*:2.9.0-alpha09。2.9.0-alpha09 版包含這些修訂項目。

新功能

  • 新增 MutableStateSerializer，用於序列化 androidx.compose.runtime.MutableState。(Idfc48、b/378895074)

API 變更

  • 以預設參數取代過載的 SavedStateHandle.saved() 委派函式 (Icd1c1)
  • AbstractSavedStateViewModelFactory 已淘汰，因為它會為每個 ViewModel 建立 SavedStateHandle，造成不必要的負擔。請改用 ViewModelProvider.Factory 和 CreationExtras.createSavedStateHandle，更有效率地建立 ViewModel。(Ia920b、b/388590327)

2.9.0-alpha08 版

2024 年 12 月 11 日

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

新功能

  • 新增 ViewModelScenario.recreate，模擬系統程序終止，重新建立受測 ViewModel 和所有相關聯的元件。(Id6a69、b/381063087)
  • 透過各自的 findViewTree API 擷取的 LifecycleOwner 和 ViewModelStoreOwner 執行個體，現在可透過檢視區塊的不相交父項 (例如 ViewOverlay) 解析。如要進一步瞭解不連續檢視區塊父項，請參閱核心版本的版本資訊或 ViewTree.setViewTreeDisjointParent 中的說明文件。(I800f4)

API 變更

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

修正錯誤

  • 這個程式庫現在使用 JSpecify 空值註解，這些註解屬於型別用途。Kotlin 開發人員應使用下列編譯器引數，強制執行正確用法：-Xjspecify-annotations=strict (這是 Kotlin 編譯器 2.1.0 版的預設值)。(Ie4340、b/326456246)
  • 文件ViewModel.onCleared清除順序。(I586c7、b/363984116)

2.9.0-alpha07 版

2024 年 11 月 13 日

發布 androidx.lifecycle:lifecycle-*:2.9.0-alpha07。2.9.0-alpha07 版包含這些修訂項目。

Kotlin Multiplatform 相容性

  • Lifecycle ViewModel SavedState 現在與 KMP 相容。您可以在通用程式碼中使用 SavedStateHandle。(Ib6394、b/334076622)

KotlinX 序列化支援

  • 我們在 SavedState 1.3.0-alpha05 中新增了 KotlinX 序列化支援，並導入 saved (延遲屬性委派)，方便您在 SavedStateHandle 中儲存 @Serializable 類別，並在程序終止及重建時自動還原這些類別。請注意，saved 委派項是延遲的，在存取前不會呼叫 init lambda，也不會將任何內容儲存至 SavedStateHandle。(I47a88、b/376026744)

    @Serializable
data class Person(val firstName: String, val lastName: String)

class MyViewModel(handle: SavedStateHandle) : ViewModel() {
    var person by handle.saved { Person("John", "Doe") }

    fun onPersonChanged(person: Person) {
        this.person = person
    }
}

API 變更

  • 在 SavedStateHandle 中新增 getMutableStateFlow，傳回 MutableStateFlow。這項新功能僅適用於按鍵，無法與 getLiveData 搭配使用。如果您嘗試使用這兩者存取相同狀態，系統會擲回例外狀況。(I04a4f、b/375408415)

2.9.0-alpha06 版

2024 年 10 月 30 日

發布 androidx.lifecycle:lifecycle-*:2.9.0-alpha06。2.9.0-alpha06 版包含這些修訂項目。

行為變更

  • Lifecycle.DESTROYED 狀態為終端狀態，如果嘗試將 Lifecycle 從這個狀態移至任何其他狀態，現在都會導致 IllegalStateException。(I116c4、b/370577987)
  • 如果傳回的 Bundle 為空，SavedStateHandle 就不會再包含任何 SavedStateProvider.saveState()。(I910b5、b/370577987)

修正錯誤

  • 當 Lifecycle 為 DESTROYED 時，Lifecycle.eventFlow 現在會正確完成 (I293b2、b/374043130)

2.9.0-alpha05 版

2024 年 10 月 16 日

已發布「androidx.lifecycle:lifecycle-*:2.9.0-alpha05」，目前沒有任何重大異動。2.9.0-alpha05 版包含這些修訂項目。

2.9.0-alpha04 版

2024 年 10 月 2 日

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

Kotlin Multiplatform

  • lifecycle-viewmodel-savedstate 模組現已設定為與 KMP 相容，為日後在通用來源集中提供 SavedStateHandle 等 API 做準備。(I503ed、I48764、b/334076622)

2.9.0-alpha03 版

2024 年 9 月 18 日

發布 androidx.lifecycle:lifecycle-*:2.9.0-alpha03。2.9.0-alpha03 版包含這些修訂項目。

修正錯誤

依附元件更新

2.9.0-alpha02 版

2024 年 9 月 4 日

發布 androidx.lifecycle:lifecycle-*:2.9.0-alpha02。2.9.0-alpha02 版包含這些修訂項目。

修正錯誤

外部貢獻

  • 將 androidx.compose.ui.platform.LocalLifecycleOwner 移至通用來源集 (KMP)。感謝 JetBrains 的 Ivan Matkov 協助修正問題。(8cd5d03)
  • 來自 Lifecycle 2.8.5：SavedStateHandle.saveable` 擴充功能委派現在支援可為空值的值。感謝 Roman Kalukiewicz 的貢獻。(0d78ea6)

2.9.0-alpha01 版

2024 年 8 月 7 日

發布 androidx.lifecycle:lifecycle-*:2.9.0-alpha01。2.9.0-alpha01 版包含這些修訂項目。

Kotlin Multiplatform

  • lifecycle-testing 現在與 KMP 相容。(Iea41e)
  • 新增對 linuxArm64 Kotlin Multiplatform 目標的支援 (I139d3、b/338268719)

新功能

  • 我們提供新的 androidx.lifecycle:lifecycle-viewmodel-testing KMP 構件，其中包含 ViewModelScenario 類別，可測試隔離狀態的 ViewModel，並支援 onCleared (所有平台) 和 SavedStateHandle (僅限 Android)。(337f68d、c9b3409、9799a95c、b/264602919)
  • 現在建立 ViewModel 時使用 ViewModelProvider 是執行緒安全，且已移除 @MainThread 註解。(Ifd978、b/237006831)

API 變更

  • 新增 CreationExtras.Key() 工廠函式，簡化匿名 CreationExtras.Key 物件的建立作業。(I970ee)
  • CreationExtras 現在包含類似對應的運算子超載，可讓您以慣用的 Kotlin 語言操作內容。這項功能可讓您搭配 CreationExtras 使用 in、+= 和 +。(Ib4353)
  • CreationExtras 現已實作 equals、hashCode 和 toString 方法。(Ib4353)
  • NewInstanceFactory 現已適用於 JVM 電腦和 Android 目標。(d3d0892)
  • 內嵌擴充功能屬性，可在 Kotlin 語言 2.0 版中安全公開基礎 Application (I39df2)

修正錯誤

  • 移除手動列出新平台 API 存取權的步驟，因為使用 AGP 7.3 以上版本 (例如 R8 3.3 版) 的 R8 時，系統會透過 API 建模自動執行這項作業，而使用 AGP 8.1 以上版本 (例如 D8 8.1 版) 時，所有建構作業都會自動執行這項作業。如果用戶端未使用 AGP，建議更新至 D8 8.1 以上版本。詳情請參閱這篇文章。(If6b4c、b/345472586)

2.8 版本

2.8.7 版

2024 年 10 月 30 日

發布 androidx.lifecycle:lifecycle-*:2.8.7。2.8.7 版包含這些修訂項目。

API 變更

  • androidx.compose.ui.platform.LocalLifecycleOwner 現已在通用來源集 (KMP) 中提供。(6a3f5b3)
  • lifecycle-runtime-compose：已移除 desktop 個構件，並新增 -jvmStubs 和 -linuxx64Stubs 個構件。這些目標都不會使用，只是為了協助 Jetbrains Compose 而設的預留位置。(6a3f5b3)

2.8.6 版

2024 年 9 月 18 日

發布 androidx.lifecycle:lifecycle-*:2.8.6。2.8.6 版包含這些修訂項目。

修正錯誤

  • NullSafeMutableLiveData Lint 錯誤已改善智慧型轉換的支援，避免誤判。(85fed6、b/181042665)

依附元件更新

2.8.5 版

2024 年 9 月 4 日

發布 androidx.lifecycle:lifecycle-*:2.8.5。2.8.5 版包含這些修訂項目。

修正錯誤

  • 更新 androidx.lifecycle.ReportFragment ProGuard 規則，以允許模糊處理。(ff898e1)

外部貢獻

  • SavedStateHandle.saveable 擴充功能委派現在支援可為空值的值。感謝 Roman Kalukiewicz 的貢獻。(0d78ea6)

2.8.4 版

2024 年 7 月 24 日

發布 androidx.lifecycle:lifecycle-*:2.8.4。2.8.4 版包含這些修訂項目。

修正錯誤

  • 當傳回的 Flow 在收到已在 LiveData 上設定的值後立即完成時 (例如使用 take(1) 時)，LiveData.asFlow() 現在可以正確處理這類情況。(I9c566)
  • Lifecycle*Effect 現在是等冪 (即如果因生命週期停止而呼叫 onStopOrDispose，除非生命週期再次回到 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 錯誤，現在您可以使用任何版本的 Compose 搭配 Lifecycle 2.8.2，不必再採取任何因應措施。(aosp/3105647、b/336842920)
  • 混合使用舊版 compileOnly Lifecycle 依附元件與 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。現在支援新增 AutoCloseable 物件，並透過 key 允許透過 getCloseable() 擷取這些物件。

  • 現在呼叫 LifecycleStartEffect 和 LifecycleResumeEffect 時若未提供金鑰，系統會傳回錯誤，這與這些 API 鏡像的 DisposableEffect API 遵循相同慣例。

  • 淘汰 LiveDataReactiveStreams.toPublisher(lifecycleOwner, liveData)，改用 LiveData.toPublisher(lifecycleOwner)。

  • lifecycle-livedata-core-ktx Kotlin 擴充功能現已移至 lifecycle-livedata-core 模組。

  • NullSafeMutableLiveData 已重構，可避免許多誤報。

生命週期 Kotlin Multiplatform 相容性

Lifecycle、LifecycleOwner、LifecycleObserver、Lifecycle.State、Lifecycle.Event 和 LifecycleRegistry 中的核心生命週期 API 現在會以與 Kotlin Multiplatform 相容的構件出貨。

受影響的構件：

  • lifecycle-common 將大多數 API 移至 common，並支援 jvm 和 iOS，以及 Android。
  • lifecycle-runtime 將大多數 API 移至 common，並支援 jvm 和 iOS，以及 Android。
  • lifecycle-runtime-ktx 現在是空的，所有 API 都已移至 lifecycle-runtime。
  • lifecycle-runtime-compose 會將所有 API 移至 common，並運送 Android 構件，與 androidx.compose 的多平台支援功能相符。

ViewModel Kotlin Multiplatform 相容性

lifecycle-viewmodel 構件和 ViewModel、ViewModelStore、ViewModelStoreOwner 和 ViewModelProvider 等 API 現在會以與 Kotlin Multiplatform 相容的構件出貨。

為配合這項變更，現在有對等的方法可使用 kotlin.reflect.KClass<T>，取代原本使用 java.lang.Class<T> 的方法 (例如 ViewModelProvider 上的方法)。

Android 一直維持二進位檔相容性，但與通用 API 介面相比，Android API 介面有幾項顯著變化：

  • 現在建構 ViewModelProvider 執行個體時，會透過 ViewModelProvider.create() 方法，而不是直接呼叫其建構函式。
  • ViewModelProvider.NewInstanceFactory 和 ViewModelProvider.AndroidViewModelFactory 僅適用於 Android。
    • 建議自訂工廠從 ViewModelProvider.Factory 擴充，並使用採用 CreationExtras 的 create 方法，或使用 viewModelFactory Kotlin DSL。
  • 在非 JVM 平台使用 ViewModelProvider，但沒有自訂工廠，會導致 UnsupportedOperationException。在 JVM 平台上，如果未提供自訂工廠，系統會使用無引數的 ViewModel 建構函式，確保相容性。
  • 如果平台不支援 Dispatchers.Main (例如 viewModelScopeEmptyCoroutineContextLinux)。

受影響的構件：

  • lifecycle-viewmodel 將大多數 API 移至 common，並支援 jvm 和 iOS，以及 Android。
  • lifecycle-viewmodel-ktx 現在是空的，所有 API 都已移至 lifecycle-viewmodel。
  • lifecycle-viewmodel-compose 會將所有 API 移至 common，並運送 Android 構件，與 androidx.compose 的多平台支援功能相符。

行為變更

  • 如果已新增具有相同 clazz: KClass<VM : ViewModel> 的 initializer，InitializerViewModelFactory (包括 viewModelFactory 建構工具函式) 現在會擲回 IllegalArgumentException。(Ic3a36)

已知問題

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 Desktop 主執行緒的檢查功能。(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 的多平台支援功能相符。為配合這項變更，Composable viewModel 方法現在除了 java.lang.Class 之外，也會接受 KClass。(b/330323282)

修正錯誤

依附元件更新

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 Multiplatform 相容性

lifecycle-viewmodel 構件和 ViewModel、ViewModelStore、ViewModelStoreOwner 和 ViewModelProvider 等 API 現在會以與 Kotlin Multiplatform 相容的構件形式發布。(b/214568825)

為配合這項變更，現在有對等的方法可使用 kotlin.reflect.KClass<T>，取代原本使用 java.lang.Class<T> 的方法 (例如 ViewModelProvider 上的方法)。

Android 一直維持二進位檔相容性，但與通用 API 介面相比，Android API 介面有幾項顯著變化：

  • 現在建構 ViewModelProvider 執行個體時，會透過 ViewModelProvider.create() 方法，而不是直接呼叫其建構函式。
  • ViewModelProvider.NewInstanceFactory 和 ViewModelProvider.AndroidViewModelFactory 僅適用於 Android。
    • 建議自訂工廠從 ViewModelProvider.Factory 擴充，並使用採用 CreationExtras 的 create 方法，或使用 viewModelFactory Kotlin DSL。
  • 在非 JVM 平台使用 ViewModelProvider，但沒有自訂工廠，會導致 UnsupportedOperationException。在 JVM 平台上，如果未提供自訂工廠，系統會使用無引數的 ViewModel 建構函式，確保相容性。
  • 如果平台不支援 Dispatchers.Main (例如 viewModelScopeEmptyCoroutineContextLinux)。

行為變更

  • 如果已新增具有相同 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 Multiplatform 相容性

  • Lifecycle、LifecycleOwner、LifecycleObserver、Lifecycle.State、Lifecycle.Event 和 LifecycleRegistry 中的核心生命週期 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 協助將 Lifecycle 遷移至 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 現在支援新增 Closeable 物件，並使用 key 透過 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 保留規則已移除。也就是說，如果經過 ProGuard 處理的程式碼想透過反射使用 API (例如使用早已淘汰的 @OnLifecycleEvent 註解)，就必須為特定用途提供自己的保留規則。

生命週期事件可觀測性

  • 現在您可以使用 Lifecycle.asFlow() 擴充功能方法，觀察 Lifecycle.Event 的 Flow，不必再使用 LifecycleEventObserver。
  • 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 中的 API 相同，適用於狀態向上變更時需要還原的情況。
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 公開為 Compose State。這相當於 lifecycle.currentStateFlow.collectAsState()，但較短。

詳情請參閱「使用 Flow 收集生命週期狀態」。

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 向後移植：修正問題，如果狀態已還原，但 save() 是在未實際儲存父項 SavedStateRegistry 中的狀態時呼叫，且狀態隨後再次還原，則程序終止後 SavedStateHandle 不會正確還原。這項修正可解決 rememberSaveable 與 Navigation Compose 的 NavHost 之間的互動問題。(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 觀察，後者會傳回 StateFlow，其中的 value 是目前的 Lifecycle.State。(Ib212d、b/209684871)
  • 現在可使用 Lifecycle.asFlow(). 將 Lifecycle.Event 視為 Flow 進行觀察 (If2c0f、b/176311030)
  • 新增了 LifecycleResumeEffect API，可根據 Lifecycle.Event.ON_RESUME 和 Lifecycle.Event.ON_PAUSE 事件回呼執行 Compose SideEffect。(I60386、b/235529345)
  • 新增 LifecycleStartEffect API，可根據 Lifecycle.Event.ON_START 和 Lifecycle.Event.ON_STOP 事件回呼執行 Compose SideEffect。(I5a8d1、b/235529345)
  • 已新增 LifecycleEventEffect API，可根據 Lifecycle.Event 執行 Compose SideEffect。(Ic9794、b/235529345)
  • 已新增 Lifecycle.collectAsState() 擴充功能，可直接將 Lifecycle.State 公開為 Compose State。這相當於 lifecycle.currentStateFlow.collectAsState()，但較短。(I11015、b/235529345)

修正錯誤

  • 如果先前的 LiveData 已設定值，LiveData.distinctUntilChanged() 擴充功能現在會設定傳回的 LiveData 的 value。這不會改變觀察行為，只有在開始觀察從 distinctUntilChanged() 傳回的 LiveData 時，才會套用來源 LiveData 的更新值。(Ib482f)
  • 與 LifecycleObserver 相關的 ProGuard 保留規則已移除。也就是說，如果經過 ProGuard 處理的程式碼想透過反射使用 API，就必須為特定用途提供自己的保留規則。(Ia12fd)

2.6 版本

2.6.2 版

2023 年 9 月 6 日

發布 androidx.lifecycle:lifecycle-*:2.6.2。查看 2.6.2 版的修訂項。

修正錯誤

  • 修正問題：如果還原狀態、呼叫 save() 時未實際儲存父項 SavedStateRegistry 中的狀態，然後再次還原狀態，則程序終止後不會正確還原 SavedStateHandle。這項修正可解決 rememberSaveable 與 Navigation Compose 的 NavHost 之間的互動問題。(aosp/2729289)

2.6.1 版

2023 年 3 月 22 日

發布 androidx.lifecycle:lifecycle-*:2.6.1。查看 2.6.1 版的修訂項目。

依附元件更新

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 現在包含用於設定初始值的建構函式。
  • 新增 collectAsStateWithLifecycle() 的 StateFlow 和 Flow 擴充功能，可從資料流收集，並以生命週期感知方式的 Compose 狀態代表其最新的值。
  • Lifecycle.launchWhenX 方法和 Lifecycle.whenX 方法已淘汰，因為在某些情況下，使用暫停調度工具可能會導致資源浪費。建議使用 Lifecycle.repeatOnLifecycle。如要進一步瞭解暫停工作一次的相關資訊，請參閱這篇說明，瞭解這項操作本質上為何不安全。
  • Kotlin 轉換 - 大量生命週期類別已轉換為 Kotlin。所有轉換的類別仍會保留與舊版的回溯相容性。下列類別的原始碼不相容變更，適用於以 Kotlin 編寫的類別：ViewTreeLifecycleOwner、LiveDataReactiveStreams、HasDefaultViewModelProviderFactory、ViewTreeViewModelStoreOwner、Transformations、ViewModelStoreOwner、LifecycleOwner

下表列出新版生命週期的來源轉換。

Lifecycle 2.5 Lifecycle 2.5 (KTX) Lifecycle 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 方法，則會遭淘汰，並由採用 Kotlin Function1 的版本取代。這項變更仍保有二進位檔相容性 (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，可傳回 Kotlin StateFlow 監控值的變化，適合做為 LiveData 的替代方案。

  • ViewModel CreationExtras - 撰寫自訂的 ViewModelProvider.Factory 時，不再需要擴充 AndroidViewModelFactory 或 AbstractSavedStateViewModelFactory 個別取得 Application 或 SavedStateHandle 的存取權，而是會透過 create(Class<T>, CreationExtras) 新的 create 超載，將這些欄位提供給「所有」ViewModelProvider.Factory 子類別做為 CreationExtras。這些額外的功能會在分別使用 Activity 1.5.0 和 Fragment 1.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，可傳回 Kotlin StateFlow 來協助監控值的變化，適合做為 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)

外部貢獻

  • 感謝 dmitrilc 修正 ViewModel 說明文件中的錯字！(#221)

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)

外部貢獻

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 的情況。
  • 生命週期狀態和事件輔助方法：為 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。您必須升級至 Activity 1.2.0 和 Fragment 1.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)

外部貢獻

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)

修正錯誤

說明文件變更

  • 更新了 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。您必須升級至 Activity 1.2.0-alpha05、Fragment 1.3.0-alpha05 和 AppCompat 1.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。您必須升級至 Activity 1.2.0-alpha01 和 Fragment 1.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()。使用 Fragment 1.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)

外部貢獻

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

新功能

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

破壞性變更

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 以外的第二個介面無法在 Kotlin by 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。