第4章 环境搭建与依赖配置

4.1 原理概述

SystemUI 作为 Android 系统级应用，其构建环境与普通 App 有显著差异：

• Gradle 依赖声明：需要引入 Navigation Compose、Lifecycle、Activity Compose 等 Jetpack 库；同时需处理 AOSP 预编译模块与 AndroidX 的互斥关系。
• minSdk 版本要求：SystemUI 必须运行在高版本 API 上（通常 ≥ 29），因为依赖的 Framework API 和窗口管理接口在低版本中不可用。
• Kotlin 与 Java 混合配置：AOSP 原生使用 Java 编写 SystemUI，但新功能建议使用 Kotlin；需要在 build.gradle 中正确配置两个源码目录及编译插件。
• Android Studio 版本兼容：推荐使用 Android Studio Hedgehog (2023.1.1) 或更高版本，Gradle 插件版本 8.x，否则可能导致 KSP/Compose 编译器插件不兼容。

4.2 环境搭建步骤

4.2.1 Gradle 依赖声明

在项目级 build.gradle.kts 或 build.gradle 中声明仓库与插件：

// build.gradle.kts (Project)
plugins {
    id("com.android.application") version "8.2.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.22" apply false
    id("org.jetbrains.kotlin.plugin.compose") version "1.9.22" apply false
}

在模块级 build.gradle.kts 中启用 Compose 并添加 Navigation 依赖：

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("org.jetbrains.kotlin.plugin.compose")
}

android {
    namespace = "com.android.systemui.navintegration"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.android.systemui.navintegration"
        minSdk = 29
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }
}

dependencies {
    // Navigation Compose
    implementation("androidx.navigation:navigation-compose:2.7.7")
    // Activity Compose
    implementation("androidx.activity:activity-compose:1.8.2")
    // Lifecycle
    implementation("androidx.lifecycle:lifecycle-runtime-compose:2.7.0")
    // Compose BOM
    implementation(platform("androidx.compose:compose-bom:2024.02.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
}

4.2.2 minSdk 版本要求

注意：实际集成到 SystemUI 时，minSdk 由 AOSP 源码树决定，通常为 29 或更高。单独编译示例项目时，建议设置 minSdk = 29 以保持兼容性。

4.2.3 Kotlin 与 Java 混合配置

SystemUI 中存在大量现有 Java 代码。在 Gradle 项目中混合配置的方法：

1. 源码目录分离：Java 源文件保留在 src/main/java/，Kotlin 源文件放置在 src/main/kotlin/。
2. 插件声明：在 build.gradle 中应用 kotlin-android 插件，Kotlin 编译器会自动处理混合文件。
3. Java 调用 Kotlin：无需额外配置，Gradle 会自动生成 Kotlin 字节码的 Java 兼容桩。
4. Kotlin 调用 Java：直接引用，但需注意 Kotlin 中不能使用 Java 的关键字（如 in、out 等）。

// 示例：Java 文件中引用 Kotlin 定义的 Object
// Java
NavController controller = NavIntegrationManager.INSTANCE.getController();

4.2.4 Android Studio 版本兼容

下表列出了常用版本组合的兼容性：

若出现 Cannot inline bytecode built with JVM target 1.8 into bytecode that is being built with JVM target 11 等错误，请检查 compileOptions 和 kotlinOptions 中的 JVM 目标一致设置为 1.8 或 17（取决于 AGP 版本）。

4.3 依赖关系与构建流程

下图展示了本章配置中涉及的核心组件及其依赖流向：

4.4 常见错误与调试

4.4.1 Compose 编译器版本不匹配

错误日志：

Execution failed for task ':app:compileDebugKotlin'.
> 'compileDebugKotlin' task (current target is 1.8) and 'kaptGenerateStubsDebugKotlin' task (current target is 11) have different jvm target values

原因：Kotlin 编译 JVM 目标与 AGP 的 compileOptions 不一致。

解决方案：在模块级 build.gradle.kts 中统一设置：

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

4.4.2 Navigation 依赖找不到 NavHost

错误日志：

Unresolved reference: NavHost

原因：未导入正确的依赖或遗漏 kotlinx.coroutines 等传递依赖。

解决方案：确认已添加 navigation-compose 依赖，并确保项目中启用了 kotlin-android 插件。

4.4.3 minSdk 过低导致 WindowInsetsControllerCompat 异常

若 minSdk < 29，某些 SystemUI 专有 API 在运行时抛出 RuntimeException。请务必设置 minSdk = 29，并在 build.gradle 中同步修改。

4.5 部署与验证

1. 在 Android Studio 中执行 Sync Project with Gradle Files，确认无报错。
2. 连接 API 29+ 的模拟器或设备，点击 Run 按钮。
3. 安装后检查应用是否有 NavHost 组件及导航过渡动画。