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

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

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

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

إتاحة ميزة لغة Java 8 باستخدام عمليات تحويل رمز البايت "desugar"
الشكل 1. إتاحة ميزة لغة Java 8 باستخدام عمليات تحويل رمز بايت desugar.

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

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

  1. تحديث المكوّن الإضافي لنظام Gradle المتوافق مع Android إلى الإصدار 3.0.0 أو إصدار أحدث
  2. لكل وحدة تستخدم ميزات لغة Java 8 (إما في رمز المصدر أو من خلال التبعيات)، عدِّل ملف build.gradle أو build.gradle.kts الخاص بالوحدة كما هو موضّح أدناه:

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 {
    ...
    // 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 أو الإصدارات الأحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android، لا يتوافق المكوِّن الإضافي مع جميع ميزات لغات Java 8. تتوفّر ميزات اللغة التالية على أي مستوى من مستويات واجهة برمجة التطبيقات:

ميزة لغة Java 8 Notes
تعبيرات اللامدا لا يتيح Android تسلسل تعبيرات lambda.
مراجع الطُرق  
كتابة التعليقات التوضيحية لا تتوفّر معلومات التعليقات التوضيحية للنوع إلا في وقت التجميع، وليس في وقت التشغيل. تتوافق المنصّة مع TYPE في المستوى 24 من واجهة برمجة التطبيقات والإصدارات الأدنى، ولكن لا تتوافق مع ElementType.TYPE_USE أو ElementType.TYPE_PARAMETER.
طرق الواجهة التلقائية والثابتة  
تكرار التعليقات التوضيحية  

بالإضافة إلى ميزات لغة Java 8 هذه، يعمل الإصدار 3.0.0 أو الإصدارات الأحدث من مكوّن Android Gradle الإضافي على توسيع نطاق التوافق مع try-مع موارد لجميع مستويات واجهات برمجة تطبيقات 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 أو إصدارات أقدم، يمكنك تفعيل ميزة تقليص الرموز لإزالة الطرق غير المستخدَمة. إذا لم تنجح هذه الطريقة، يمكنك استخدام مكتبة بديلة لا تستخدم الطرق غير المتوافقة.

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

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

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

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

تتوافق مجموعة واجهات برمجة التطبيقات التالية عند إنشاء تطبيقك باستخدام الإصدار 4.0.0 من مكوّن Android 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 من المكوّن الإضافي لنظام Gradle المتوافق مع Android أو الإصدارات الأحدث، تتوافق واجهات برمجة تطبيقات Java 11 الإضافية مثل مجموعة فرعية من حزمة java.nio.file.

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

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

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

  1. تحديث المكوّن الإضافي لنظام Gradle المتوافق مع Android إلى الإصدار 4.0.0 (أو إصدار أحدث)
  2. أدرِج ما يلي في ملف build.gradle أو build.gradle.kts الخاص بوحدة التطبيق:

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 {
    // 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+ والحدّ الأدنى من إصدار مكوّن Android Gradle الإضافي الذي يتوافق مع كل إصدار:

الإصدار الحد الأدنى لإصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android
1.1.9 4.0.0
1.2.3 7.3.0
2.0.3 الإصدار 7.4.0 -alpha10

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