使用 Java 8 語言功能和 API

Android Gradle 外掛程式 3.0.0 及以上版本支援所有 Java 7 語言功能及某些 Java 8 語言功能的子集 (因平台版本而異)。使用 Android Gradle 外掛程式 4.0.0 及以上版本建構應用程式時，您可以使用多種 Java 8 語言 API，而且應用程式不需要最低 API 級別。

本頁說明您可以使用的 Java 8 語言功能、如何正確設定專案以使用此功能，以及您可能會遇到哪些已知問題。如有需要，請觀看以下影片。

注意：開發 Android 應用程式時，您可以自選使用 Java 8 語言功能。您可以將專案的來源和目標相容性值設為 Java 7，但仍須使用 JDK 8 進行編譯。

Android Gradle 外掛程式提供使用 Java 8 語言功能和第三方程式庫的內建支援。如圖 1 所示，預設的工具鏈會執行稱為 desugar 的位元碼轉換來實作新的語言功能，做為 D8/R8 類別檔案編譯至 dex 程式碼的一部分。

圖 1. 支援使用 desugar 個位元碼的 Java 8 語言功能。

支援 Java 8 語言功能 (Android Gradle 外掛程式 3.0.0 以上版本)

如要開始使用支援的 Java 8 語言功能，請將 Android 外掛程式更新為 3.0.0 (或更高版本)。之後，針對每個使用 Java 8 語言功能的模組 (無論其原始碼還是依附元件)，請更新模組的 build.gradle 檔案，如下所示：

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 語言功能以外，外掛程式 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+ 語言功能脫糖，並不提供任何其他類別和 API (例如 java.util.stream.*)，可用於舊版 Android。Android Gradle 外掛程式 4.0.0 或以上版本才支援部分 Java API 脫糖，詳情請見下一節。

支援 Java 8+ API 脫糖 (Android Gradle 外掛程式 4.0.0 以上版本)

如果您使用 Android Gradle 外掛程式 4.0.0 或以上版本建構應用程式，這個外掛程式會擴充支援各種 Java 8 語言 API，且不需要應用程式的最低 API 級別。

外掛程式可支援這個額外平台版本，因為外掛程式 4.0.0 和後續版本，會將脫糖引擎擴充為也對 Java 語言 API 進行脫糖。因此，您可以在支援較舊 Android 版本的應用程式中納入支援標準語言 API (例如 java.util.streams) 的標準語言 API。

使用 Android Gradle 外掛程式 4.0.0 或以上版本建構應用程式時，系統會支援下列 API：

• 依序串流 (java.util.stream)
• 「java.time」的子集
• java.util.function
• java.util.{Map,Collection,Comparator} 的近期新增項目
• 選用 (java.util.Optional、java.util.OptionalInt 和 java.util.OptionalDouble) 和其他適用於上述 API 的新類別
• java.util.concurrent.atomic的新增項目 (AtomicInteger、AtomicLong和AtomicReference上的新方法)
• ConcurrentHashMap (修正 Android 5.0 錯誤)

如需完整的支援 API 清單，請參閱 Java 8+ API 脫糖所需的 API。

為了支援這些語言 API，這個外掛程式會編譯單獨的 DEX 檔案，其中包含缺少 API 的實作項目，並將其納入應用程式。這個脫糖程序會重新編寫應用程式的程式碼，並在執行階段改為使用這個程式庫。

如要在任何 Android 平台版本上支援這些語言 API，請將 Android 外掛程式更新為 4.0.0 (或更高版本)，然後在 中加入應用程式模組的 build.gradle 檔案：

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 {
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.5'
}

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 {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.1.5")
}

請注意，在下列情況下，您可能需要在程式庫模組的build.gradle檔案中加入上述程式碼片段：

• 程式庫模組的檢測設備測試會使用這些語言 API (直接或透過程式庫模組或其依附元件)。因此，您的檢測設備測試 APK 會提供缺少的 API。

• 您希望單獨執行程式庫模組中的 lint。可協助 lint 辨識語言 API 的有效用量，並避免誤報警示。

另請注意，只有在使用 R8 壓縮時，API 脫糖作業可以與壓縮結合使用。

版本

下表顯示 Java 8+ API 程式庫版本以及支援各版本的最低 Android Gradle 外掛程式版本。