使用 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 檔案,如下所示:

Groovy

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"
    }
}

Kotlin

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 語言功能 附註
Lambda 運算式 請注意,Android 不支援序列化 lambda 運算式。
方法參考資料  
類型註解 類型註解資訊僅於編譯期間取得,無法在執行階段提供。此外,平台支援 API 級別 24 及以下的 TYPE,但不支援 ElementType.TYPE_USEElementType.TYPE_PARAMETER
預設和靜態介面方法  
重複註解  

除了上述 Java 8 語言功能以外,外掛程式 3.0.0 及以上版本將 try-with-resources 的支援範圍擴充至所有 Android API 級別。

Desugar 目前不支援 MethodHandle.invokeMethodHandle.invokeExact。如果您的原始碼或其中一個模組依附元件使用其中一種方法,請指定 minSdkVersion 26 或以上版本。否則,您會收到下列錯誤訊息:

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

在某些情況下,即使包含在程式庫依附元件中,模組仍可能不會使用 invokeinvokeExact 方法。因此,若要繼續使用 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.Optionaljava.util.OptionalIntjava.util.OptionalDouble) 和其他適用於上述 API 的新類別
  • java.util.concurrent.atomic的新增項目 (AtomicIntegerAtomicLongAtomicReference上的新方法)
  • ConcurrentHashMap (修正 Android 5.0 錯誤)

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

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

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

Groovy

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'
}

Kotlin

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 外掛程式版本。

版本 Android Gradle 外掛程式最低版本
1.1.5 4.0.0
1.2.0 7.3.0-beta03
如要進一步瞭解所使用的 Java 8+ API 程式庫版本,請參閱 desugar_jdk_libs GitHub 存放區中的 CHANGELOG.md 檔案