📚 课程目录第2章集成SavedStateHandle依赖

2. 集成SavedStateHandle依赖

SavedStateHandle 是 AndroidX Lifecycle 组件的一部分，必须通过明确的 Gradle 依赖声明引入到模块中。本章以前沿实战视角，演示如何在 build.gradle 中正确声明依赖、验证版本兼容性以及配置 AndroidX 组件版本，避免因依赖冲突或版本不匹配导致的编译失败或运行时异常。

2.1 Gradle 依赖声明

SavedStateHandle 的核心依赖为 lifecycle-viewmodel-savedstate，在模块级 build.gradle（或 build.gradle.kts）中添加如下声明：

Groovy DSL 示例

// 模块级 build.gradle
dependencies {
    // ViewModel + SavedStateHandle 核心包
    implementation "androidx.lifecycle:lifecycle-viewmodel-savedstate:2.8.4"

    // 可选：LiveData 或 Kotlin 协程扩展
    implementation "androidx.lifecycle:lifecycle-livedata-ktx:2.8.4"
    implementation "androidx.lifecycle:lifecycle-runtime-ktx:2.8.4"
}

Kotlin DSL 示例

// 模块级 build.gradle.kts
dependencies {
    implementation("androidx.lifecycle:lifecycle-viewmodel-savedstate:2.8.4")
    // 可选扩展
    implementation("androidx.lifecycle:lifecycle-livedata-ktx:2.8.4")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.4")
}

版本号全局控制：建议在根项目 build.gradle 或 libs.versions.toml 中定义版本变量，统一管理。

2.2 版本兼容性检查

SavedStateHandle 自 Lifecycle 2.2.0 起可用，但不同版本对 compileSdk、minSdk 及 AndroidX 总线版本有隐性要求。下表列出常用 AndroidX 组件版本与 lifecycle-viewmodel-savedstate 的兼容关系：

lifecycle-viewmodel-savedstate 版本	最小 compileSdk	最小 minSdk	兼容的 appcompat	兼容的 activity
2.2.0 – 2.3.1	28	14	1.1.0+	1.1.0+
2.4.0 – 2.5.1	31	16	1.4.0+	1.4.0+
2.6.0 – 2.7.0	33	19	1.6.0+	1.6.0+
2.8.0+	34	21	1.7.0+	1.8.0+

若不满足上述条件，编译期可能出现以下错误：

Cannot resolve symbol 'SavedStateHandle' —— 依赖未添加或版本不可用。
API 'variant.getApplicationId()' is obsolete —— 与 AGP 版本不匹配，需升级 Gradle 插件。
java.lang.NoClassDefFoundError: androidx.lifecycle.SavedStateHandle —— 运行时版本冲突，需检查 transitive 依赖树。

2.3 AndroidX 组件版本配置

为确保 SavedStateHandle 正常工作，需同步配置相关 AndroidX 组件版本。推荐使用 版本目录（Version Catalog）统一管理：

libs.versions.toml (gradle 目录)

[versions]
lifecycle = "2.8.4"
appcompat = "1.7.0"
activity = "1.9.3"
fragment = "1.8.4"

[libraries]
lifecycle-viewmodel-savedstate = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-savedstate", version.ref = "lifecycle" }
lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycle" }
appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
activity-ktx = { group = "androidx.activity", name = "activity-ktx", version.ref = "activity" }

在模块 build.gradle.kts 中引用

dependencies {
    implementation(libs.lifecycle.viewmodel.savedstate)
    implementation(libs.lifecycle.runtime.ktx)
    implementation(libs.appcompat)
    implementation(libs.activity.ktx)
}

  调试命令：运行 ./gradlew :app:dependencies --configuration implementation 查看完整依赖树，确认 SavedStateHandle 版本及传递依赖。

2.4 常见错误与解决

重复依赖冲突：多个模块引入不同版本时，使用 force 或 strictly 约束。在 build.gradle.kts 中配置：

configurations.all {
    resolutionStrategy {
        force("androidx.lifecycle:lifecycle-viewmodel-savedstate:2.8.4")
    }
}

minSdk 过低：若 minSdk < 21，需在 AndroidManifest.xml 中保留 android:extractNativeLibs="true"，或升级 minSdk 至 21+。
API 不可见：编译时提示 setTagIfAbsent 或 getViewModelStore 为 internal，需确保依赖了 activity-ktx 而非仅 activity。

2.5 性能与稳定性优化

避免在 build.gradle 中硬编码版本号，使用版本目录便于升级和同步。

启用 R8 全模式 混淆时，保留 SavedStateHandle 相关类：

-keep class androidx.lifecycle.SavedStateHandle { *; }
-keep class * extends androidx.lifecycle.ViewModel {
    public <init>(...);
}

使用 lintChecks 插件检查依赖版本兼容性，集成 com.osv:gradle-plugin 持续追踪已知漏洞。

注意：AndroidX Lifecycle 2.8.x 已移除对 Java 8 前端的支持，若项目仍使用 Java 7 编码，请升级至 Java 8 或使用 API 19+ 变通方案。