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

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

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

ملاحظة: عند تطوير تطبيقات لنظام Android باستخدام Java 8 ميزات اللغة اختيارية. يمكنك الاحتفاظ بمصدر مشروعك وهدفه تم ضبط قيم التوافق على Java 7، ولكن لا تزال بحاجة إلى التجميع باستخدام JDK 8.

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

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

ملاحظة: يؤدي اختيارك لمستوى رمز البايت إلى تحقيق التوازن بين الوظائف والإصدار السرعة. يتضمّن المستوى 6 من رمز البايت إصدارًا أسرع وعددًا أقل. الأخرى، بينما يتميز المستوى 7 برمز البايت 7 بتوازن بين الميزات وسرعة الإصدار، ورمز البايت 8 هو أكثر من حيث الميزات والنُسخ الأبطأ.

دعم ميزة لغة Java 8 (المكوّن الإضافي لنظام Gradle المتوافق مع Android الإصدار 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"
    }
}

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

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

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

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

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

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

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

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

تتوفّر المجموعة التالية من واجهات برمجة التطبيقات عند إنشاء تطبيقك باستخدام نظام التشغيل Android. الإصدار 4.0.0 من المكوّن الإضافي لنظام 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")
}

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 {
    // 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 في وحدة المكتبة بشكل منفصل. الهدف من ذلك هو المساعدة تتعرّف أداة Lint على الاستخدامات الصالحة لواجهات برمجة التطبيقات للّغة وتتجنّب الإبلاغ عن الخطأ. الجديدة.

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

الإصدارات

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

الإصدار	الحد الأدنى لإصدار المكوّن الإضافي لنظام 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 في مستودع GitHub desugar_jdk_libs.