使用 Java 8 语言特性和 API

Android Gradle 插件 3.0.0 及更高版本支持所有 Java 7 语言特性以及部分 Java 8 语言特性（这些特性因平台版本而异）。当您使用 Android Gradle 插件 4.0.0 及更高版本构建应用时，可以使用某些 Java 8 语言 API，而无需为您的应用设置最低 API 级别。

本页面介绍了您可以使用的 Java 8 语言特性、如何正确配置项目以使用这些特性，以及您可能会遇到的任何已知问题。如需了解 Java 8 语言特性的概览，请观看以下视频。

Android Gradle 插件为使用某些 Java 8 语言特性和使用这些特性的第三方库提供了内置支持。默认工具链通过执行字节码转换（称为 desugar）来实现新的语言特性，这是将类文件编译为 DEX 代码的 D8/R8 编译的一部分，如图 1 所示。

Java 8 语言特性支持 (Android Gradle 插件 3.0.0+)

要开始使用支持的 Java 8 语言特性

1. 将 Android Gradle 插件更新到 3.0.0 或更高版本。
2. 对于使用 Java 8 语言特性（无论是在其源代码中还是通过依赖项）的每个模块，请更新模块的 build.gradle 或 build.gradle.kts 文件，如下所示

android {
    ...
    // Configure only for each module that uses Java 8
    // language features (either in its source code or
    // through dependencies).
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

android {
    ...
    // Configure only for each module that uses Java 8
    // language features (either in its source code or
    // through dependencies).
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

当您使用 Android Gradle 插件 3.0.0 及更高版本构建应用时，该插件不支持所有 Java 8 语言特性。以下语言特性在任何 API 级别上都可用

除了这些 Java 8 语言特性之外，Android Gradle 插件 3.0.0 及更高版本将对 try-with-resources 的支持扩展到所有 Android API 级别。

Desugar 不支持 MethodHandle.invoke 或 MethodHandle.invokeExact。如果您的源代码或某个模块依赖项使用了这些方法之一，则需要指定 minSdkVersion 26 或更高版本。否则，您会收到以下错误

Dex: Error converting bytecode to dex:
Cause: signature-polymorphic method called without --min-sdk-version >= 26

在某些情况下，即使 invoke 或 invokeExact 方法包含在库依赖项中，您的模块也可能没有使用它们。要继续在 minSdkVersion 25 或更低版本中使用该库，请启用代码压缩以移除未使用的方法。如果这不起作用，请考虑使用不使用不受支持方法的替代库。

Android Gradle 插件 3.0.0 及更高版本上的 Java 8+ 语言特性 desugaring 不会使任何额外的类和 API（例如 java.util.stream.*）在较旧的 Android 版本上可用。从 Android Gradle 插件 4.0.0 或更高版本开始，支持部分 Java API desugaring，如以下部分所述。

Java 8+ API desugaring 支持 (Android Gradle 插件 4.0.0+)

如果您使用 Android Gradle 插件 4.0.0 或更高版本构建应用，则该插件会将对使用许多 Java 8 语言 API 的支持扩展到您的应用无需最低 API 级别。对于 Android Gradle 插件 7.4.0 或更高版本，还可以使用 desugared library 2.0.0 或更高版本中的许多 Java 11 语言 API。

之所以能够额外支持较旧的平台版本，是因为插件 4.0.0 及更高版本扩展了 desugaring 引擎，使其也能对 Java 语言 API 进行 desugaring。您可以将仅在最新 Android 版本中可用的标准语言 API（例如 java.util.streams）包含在支持较旧 Android 版本的应用中。

使用 Android Gradle 插件 4.0.0 或更高版本构建应用时，支持以下 API 集

• 顺序流 (java.util.stream)
• java.time 的一个子集
• java.util.function
• java.util.{Map,Collection,Comparator} 的最新添加内容
• Optional 类（java.util.Optional、java.util.OptionalInt 和 java.util.OptionalDouble）以及一些新类
• java.util.concurrent.atomic 的一些添加内容（AtomicInteger、AtomicLong 和 AtomicReference 上的新方法）
• ConcurrentHashMap（包含针对 Android 5.0 的错误修复）

使用 Android Gradle 插件 7.4.0 或更高版本，还支持其他 Java 11 API，例如 java.nio.file 软件包的一个子集。

如需支持的 API 的完整列表，请访问通过 desugaring 可用的 Java 8+ API 和通过 desugaring 可用的 Java 11+ API。

为了支持这些语言 API，该插件会编译一个单独的 DEX 文件，其中包含缺失 API 的实现，并将其包含在您的应用中。desugaring 过程会重写您的应用代码，使其在运行时改为使用此库。编译到单独 DEX 文件中的源代码可在 desugar_jdk_libs GitHub 代码库中找到。

要在任何版本的 Android 平台上启用对这些语言 API 的支持

1. 将 Android Gradle 插件更新到 4.0.0（或更高版本）。
2. 在您的应用模块的 build.gradle 或 build.gradle.kts 文件中包含以下内容

android {
    defaultConfig {
        // Required when setting minSdkVersion to 20 or lower
        multiDexEnabled = true
    }

    compileOptions {
        // Flag to enable support for the new language APIs

        // For AGP 4.1+
        isCoreLibraryDesugaringEnabled = true
        // For AGP 4.0
        // coreLibraryDesugaringEnabled = true

        // Sets Java compatibility to Java 8
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}

dependencies {
    // For AGP 7.4+
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.3")
    // For AGP 7.3
    // coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.2.3")
    // For AGP 4.0 to 7.2
    // coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.1.9")
}

android {
    defaultConfig {
        // Required when setting minSdkVersion to 20 or lower
        multiDexEnabled true
    }

    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    // For AGP 7.4+
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.3'
    // For AGP 7.3
    // coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.2.3'
    // For AGP 4.0 to 7.2
    // coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.9'
}

另请注意，您可能还需要在库模块的 build.gradle 或 build.gradle.kts 文件中包含前面的代码片段，如果

• 库模块的插桩测试（instrumented tests）使用这些语言 API（无论是直接使用还是通过库模块或其依赖项使用）。这是为了让缺失的 API 可用于您的插桩测试 APK。

• 您希望在隔离状态下对库模块运行 lint。这有助于 lint 识别语言 API 的有效用法并避免报告误报警告。

另请注意，API desugaring 可以与代码压缩结合使用，但仅在使用 R8 压缩器时。

版本

下表显示了 Java 8+ API 库的版本以及支持每个版本的最低 Android Gradle 插件版本

有关 Java 8+ API 库版本的详细信息，请参阅 desugar_jdk_libs GitHub 代码库中的 CHANGELOG.md 文件。