استخدام ميزات لغة Java 8 وواجهات برمجة التطبيقات

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يتوافق المكوّن الإضافي لنظام Gradle المتوافق مع Android 3.0.0 والإصدارات الأحدث مع جميع ميزات لغة Java 7 ومجموعة فرعية من ميزات لغة Java 8 التي تختلف حسب إصدار النظام الأساسي. عند إنشاء تطبيقك باستخدام الإصدار 4.0.0 من "مكوّن إضافي لـ Gradle في Android" والإصدارات الأحدث، يمكنك استخدام بعض واجهات برمجة تطبيقات لغة Java 8 بدون اشتراط الحد الأدنى من مستوى واجهة برمجة التطبيقات لتطبيقك.

توضِّح هذه الصفحة ميزات لغة Java 8 التي يمكنك استخدامها وكيفية ضبط مشروعك بشكل صحيح لاستخدامها وأي مشاكل معروفة قد تواجهها. يمكنك مشاهدة الفيديو التالي للحصول على نظرة عامة على ميزات لغة Java 8.

يقدّم المكوّن الإضافي لنظام Android Gradle دعمًا مضمّنًا لاستخدام ميزات معيّنة من لغة Java 8 والمكتبات التابعة لجهات خارجية التي تستخدمها. تُنفِّذ مجموعة الأدوات التلقائية ميزات اللغة الجديدة من خلال تنفيذ عمليات تحويل رمز الآلة، والتي تُعرف باسم desugar، كجزء من عملية تجميع D8/R8 لملفات الفئات إلى رمز DEX، كما هو موضّح في الشكل 1.

إتاحة ميزات لغة Java 8 (الإصدار 3.0.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android والإصدارات الأحدث)

لبدء استخدام ميزات لغة Java 8 المتوافقة:

1. حدِّث المكوّن الإضافي لنظام Gradle المتوافق مع Android إلى الإصدار 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"
    }
}

عند إنشاء تطبيقك باستخدام الإصدار 3.0.0 من "مكوّن Android Gradle الإضافي" والإصدارات الأحدث، لا يتيح المكوّن تضامنًا مع جميع ميزات لغة Java 8. تتوفّر ميزات اللغة التالية على أي مستوى من مستويات واجهة برمجة التطبيقات:

بالإضافة إلى ميزات لغة Java 8 هذه، يوفّر الإصدار 3.0.0 من مكوّن Gradle الإضافي المتوافق مع Android والإصدارات الأحدث إمكانية استخدام العلامة try-with-resources في جميع مستويات واجهة برمجة التطبيقات لنظام Android.

لا تتوافق أداة 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 أو الإصدارات الأقدم، فعِّل ميزة تقليل حجم الرموز البرمجية لإزالة methods غير المستخدَمة. إذا لم تنجح هذه الطريقة، ننصحك باستخدام مكتبة بديلة لا تستخدم الطرق غير المتوافقة.

توفّر لغة Java 8 والإصدارات الأحدث ميزة إزالة رمز Sugar في المكوّن الإضافي لنظام Gradle المتوافق مع Android 3.0.0 والإصدارات الأحدث، ولا تتيح استخدام أي فئات وواجهات برمجة تطبيقات إضافية (مثل java.util.stream.*) على إصدارات Android القديمة. يتوفّر دعم إزالة رمز Java API بشكل جزئي من المكوّن الإضافي لنظام Gradle المتوافق مع Android 4.0.0 أو إصدار أحدث، كما هو موضّح في القسم التالي.

إتاحة إزالة رمز واجهة برمجة التطبيقات من Java 8 والإصدارات الأحدث (الإصدار 4.0.0 من "مكوّن إضافي لنظام Gradle المتوافق مع Android" والإصدارات الأحدث)

إذا كنت بصدد إنشاء تطبيقك باستخدام الإصدار 4.0.0 أو إصدار أحدث من "مكوّن إضافي لـ Gradle في Android"، يوفّر المكوّن الإضافي إمكانية استخدام عدد من واجهات برمجة التطبيقات بلغة Java 8 بدون اشتراط الحد الأدنى من مستوى واجهة برمجة التطبيقات لتطبيقك. باستخدام الإصدار 7.4.0 أو إصدار أحدث من "مكوّن إضافي لـ Gradle في Android"، يتوفّر أيضًا عدد من واجهات برمجة التطبيقات بلغة Java 11 مع مكتبة 2.0.0 أو إصدار أحدث تم إزالة السكر منها.

يمكن استخدام هذه الميزة الإضافية لإصدارات المنصة القديمة لأنّ الإصدار 4.0.0 من المكوّن الإضافي وما بعده يمدّد محرّك إزالة المعالجة السكرية لإزالة المعالجة السكرية من واجهات برمجة التطبيقات بلغة Java أيضًا. يمكنك تضمين واجهات برمجة التطبيقات اللغوية العادية التي كانت متاحة فقط في إصدارات Android الحديثة (مثل java.util.streams) في التطبيقات المتوافقة مع إصدارات Android القديمة.

تتوفّر المجموعة التالية من واجهات برمجة التطبيقات عند إنشاء تطبيقك باستخدام الإصدار 4.0.0 أو الإصدارات الأحدث من "مكوّن Android IDE لـ Gradle":

• أحداث البث التسلسلي (java.util.stream)
• مجموعة فرعية من java.time
• java.util.function
• الإضافات الأخيرة إلى java.util.{Map,Collection,Comparator}
• العناصر الاختيارية (java.util.Optional وjava.util.OptionalInt و java.util.OptionalDouble) وبعض الفئات الجديدة
• بعض الإضافات إلى java.util.concurrent.atomic (طُرق جديدة في AtomicInteger وAtomicLong وAtomicReference)
• ConcurrentHashMap (تتضمّن إصلاحات للأخطاء في Android 5.0)

باستخدام المكوّن الإضافي 7.4.0 أو الإصدارات الأحدث من Android Gradle، يتم إتاحة واجهات برمجة تطبيقات Java 11 إضافية، مثل مجموعة فرعية من حزمة java.nio.file.

للحصول على قائمة كاملة بواجهات برمجة التطبيقات المتوافقة، يُرجى الانتقال إلى واجهات برمجة تطبيقات Java 8 والإصدارات الأحدث المتوفّرة من خلال إزالة رمز السكر وواجهات برمجة تطبيقات Java 11 والإصدارات الأحدث المتوفّرة من خلال إزالة رمز السكر.

ولتتوافق هذه الواجهات مع لغات البرمجة، يُنشئ المكوّن الإضافي ملفًا DEX منفصلاً يحتوي على تنفيذ لواجهات برمجة التطبيقات غير المتوفّرة ويُدرِجه في تطبيقك. تعيد عملية إزالة الرمز البرمجي المُبسّط كتابة رمز تطبيقك لاستخدام هذه المكتبة بدلاً من ذلك عند وقت التشغيل. تتوفّر الرموز البرمجية المصدر التي تم تجميعها في ملف DEX منفصل في مستودع GitHub الخاص بملف desugar_jdk_libs.

لتفعيل واجهات برمجة التطبيقات هذه للغات على أي إصدار من نظام Android الأساسي:

1. حدِّث المكوّن الإضافي لنظام Gradle المتوافق مع Android إلى الإصدار 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 الخاص بالمكتبة الوحدة في الحالات التالية:

• تستخدِم الاختبارات المزوّدة بأدوات قياس أداء وحدة المكتبة واجهات برمجة التطبيقات هذه للغة (إما بشكل مباشر أو من خلال وحدة المكتبة أو العناصر التي تعتمد عليها). يهدف ذلك إلى توفير واجهات برمجة التطبيقات غير المتوفّرة لحزمة APK الاختبارية التي تم اختبارها.

• إذا كنت تريد تشغيل lint على وحدة المكتبة بشكل منفصل. ويهدف ذلك إلى مساعدة أداة فحص الأخطاء في التعرّف على الاستخدامات الصالحة لواجهات برمجة التطبيقات للغة وتجنُّب الإبلاغ عن تحذيرات خاطئة.

يُرجى العلم أيضًا أنّه يمكن دمج إزالة رمز السكر في واجهة برمجة التطبيقات مع تصغير الحجم، ولكن عند استخدام أداة تصغير الحجم R8 فقط.

الإصدارات

يعرض الجدول التالي إصدارات مكتبة Java 8+ API و الحد الأدنى لإصدار مكوّن إضافي Gradle لنظام التشغيل Android المتوافق مع كل إصدار:

لمعرفة تفاصيل عن إصدارات مكتبة Java 8+ API، يُرجى الاطّلاع على ملف CHANGELOG.md في مستودع desugar_jdk_libs GitHub.