ملاحظات الإصدار 8.10 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

أصبح مستودع JCenter للقراءة فقط في 31 آذار (مارس) 2021. لمزيد من المعلومات، يُرجى الاطّلاع على تعديل خدمة JCenter.

ملاحظة مهمة: للحصول على سجلّ تفصيلي عن إيقاف واجهة برمجة التطبيقات "المكوّن الإضافي لنظام Gradle المتوافق مع Android" نهائيًا و إزالتها، اطّلِع على تعديلات واجهة برمجة التطبيقات "المكوّن الإضافي لنظام Gradle المتوافق مع Android".

يستند نظام التصميم في "استوديو Android" إلى Gradle، ويضيف المكوّن الإضافي لنظام Gradle المتوافق مع Android عدة ميزات خاصة بتصميم تطبيقات Android. ومع أنّ المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) يتم تحديثه عادةً في خطوة القفل باستخدام "استوديو Android"، يمكن تشغيل المكوّن الإضافي (وباقي نظام Gradle) بشكل مستقل عن "استوديو Android" ويتم تحديثه بشكل منفصل.

توضّح هذه الصفحة كيفية إبقاء أدوات Gradle محدّثة باستمرار، وتعرض محتوى التحديثات الأخيرة. للاطّلاع على ملاحظات الإصدارات السابقة من المكوّن الإضافي لنظام Gradle المتوافق مع Android، يُرجى الانتقال إلى ملاحظات الإصدارات السابقة.

لمعرفة المشاكل التي تم حلّها في هذا الإصدار من المكوّن الإضافي لنظام Gradle المتوافق مع Android، اطّلِع على المشاكل التي تم إغلاقها.

للحصول على ملخّص على مستوى عالٍ للتغييرات الأساسية القادمة في المكوّن الإضافي لنظام Gradle المتوافق مع Android، يمكنك الاطّلاع على خارطة طريق المكوّن الإضافي لنظام Gradle المتوافق مع Android.

للحصول على تفاصيل عن كيفية ضبط إصدارات Android باستخدام Gradle، يُرجى الاطّلاع على الصفحات التالية:

• ضبط الإصدار
• مرجع DSL للمكوّن الإضافي لنظام Gradle المتوافق مع Android
• مرجع Gradle DSL
• دليل مستخدم أداء Gradle

لمزيد من المعلومات عن نظام إنشاء Gradle، يُرجى الاطّلاع على دليل مستخدم Gradle.

تحديث المكوّن الإضافي لنظام Gradle المتوافق مع Android

عند تحديث Android Studio، قد تتلقّى إشعارًا يطلب منك تحديث المكوّن الإضافي لنظام Gradle المتوافق مع Android تلقائيًا إلى أحدث إصدار متاح. يمكنك اختيار قبول التحديث أو تحديد إصدار يدويًا استنادًا إلى متطلبات إنشاء مشروعك.

يمكنك تحديد إصدار المكوّن الإضافي في قائمة الملف > بنية المشروع > المشروع في "استوديو Android"، أو ملف build.gradle.kts على المستوى الأعلى. ينطبق إصدار المكوّن الإضافي على جميع الوحدات التي تم إنشاؤها في مشروع "استوديو Android" هذا. يضبط المثال التالي المكوّن الإضافي على الإصدار 8.10.0 منملف build.gradle.kts:

Kotlin

plugins {
    id("com.android.application") version "8.10.0" apply false
    id("com.android.library") version "8.10.0" apply false
    id("org.jetbrains.kotlin.android") version "2.1.20" apply false
}

رائع

plugins {
    id 'com.android.application' version '8.10.0' apply false
    id 'com.android.library' version '8.10.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.1.20' apply false
}

تحذير: يجب عدم استخدام التبعيات الديناميكية في أرقام الإصدار، مثل 'com.android.tools.build:gradle:8.10.+'. يمكن أن يؤدي استخدام هذه الميزة إلى إجراء تحديثات غير متوقّعة للإصدارات وصعوبة حلّ الاختلافات بين الإصدارات.

إذا لم يتم تنزيل إصدار المكوّن الإضافي المحدّد، ينزّله Gradle في المرة التالية التي تُنشئ فيها مشروعك أو بالنقر على ملف > مزامنة المشروع مع ملفات Gradle من شريط قوائم Android Studio.

تعديل Gradle

عند تحديث Android Studio، قد تتلقّى إشعارًا يطلب منك أيضًا تحديث Gradle إلى أحدث إصدار متاح. يمكنك اختيار قبول التحديث أو تحديد إصدار يدويًا استنادًا إلى متطلبات إنشاء مشروعك.

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

إصدار المكوِّن الإضافي	الحد الأدنى لإصدار Gradle المطلوب
8.10	8.11.1
8.9	8.11.1
8.8	8.10.2
8.7	8.9
8.6	8.7
8.5	8.7
8.4	8.6
8.3	8.4
8.2	8.2
8.1	من نظام التشغيل Android
من نظام التشغيل Android	من نظام التشغيل Android

إصدارات سابقة

إصدار المكوِّن الإضافي	إصدار Gradle المطلوب
7.4	7.5
7.3	7.4
7.2	7.3.3
7.1	7.2
7	7
4.2.0 والإصدارات الأحدث	6.7.1
4.1.0 والإصدارات الأحدث	6.5 أو إصدار أحدث
4.0.0 والإصدارات الأحدث	6.1.1 والإصدارات الأحدث
3.6.0 - 3.6.4	5.6.4 والإصدارات الأحدث
3.5.0 - 3.5.4	5.4.1 والإصدارات الأحدث
3.4.0 - 3.4.3	5.1.1 والإصدارات الأحدث
3.3.0 - 3.3.3	4.10.1 والإصدارات الأحدث
3.2.0 - 3.2.1	4.6 أو إصدار أحدث
3.1.0 والإصدارات الأحدث	4.4 أو إصدار أحدث
3.0.0 والإصدارات الأحدث	الإصدار 4.1 أو الإصدارات الأحدث
2.3.0 والإصدارات الأحدث	الإصدار 3.3 أو الإصدارات الأحدث
2.1.3 - 2.2.3	‫2.14.1 - 3.5
2.0.0 - 2.1.2	2.10 - 2.13
1.5.0	2.2.1 - 2.13
1.2.0 - 1.3.1	2.2.1 - 2.9
1.0.0 - 1.1.3	2.2.1 - 2.3

يمكنك تحديد إصدار Gradle في قائمة ملف > هيكل المشروع > المشروع في "استوديو Android"، أو يمكنك تعديل إصدار Gradle باستخدام سطر الأوامر. الطريقة المفضّلة هي استخدام أداة سطر الأوامر Gradle Wrapper التي تعدّل النصوص البرمجية gradlew. يضبط المثال التالي إصدار Gradle على 8.10 باستخدام Gradle Wrapper. يُرجى العلم أنّه عليك تنفيذ هذا الأمر مرتين لترقية كلّ من Gradle و Gradle Wrapper نفسه (لمزيد من المعلومات، يُرجى الاطّلاع على ترقية Gradle Wrapper).

gradle wrapper --gradle-version 8.10

ومع ذلك، قد يتعذّر تنفيذ ذلك في بعض الحالات، على سبيل المثال إذا كنت قد عدّلت للتو AGP ولم يعُد متوافقًا مع إصدار Gradle الحالي. في هذه الحالة، عليك تعديل مرجع توزيع Gradle فيملف gradle/wrapper/gradle-wrapper.properties. في المثال التالي، يتم ضبط الإصدار من Gradle على 8.10 في ملف gradle-wrapper.properties.

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.10-bin.zip
...

توافق المكوّن الإضافي لنظام Gradle المتوافق مع Android و"استوديو Android"

يستند نظام التصميم في Android Studio إلى Gradle، ويضيف المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) العديد من الميزات الخاصة بإنشاء تطبيقات Android. يسرد الجدول التالي إصدار AGP المطلوب لكل إصدار من Android Studio.

إذا لم يكن مشروعك متوافقًا مع إصدار معيّن من "استوديو Android"، سيظل بإمكانك فتح مشروعك وتعديله باستخدام إصدار قديم من "استوديو Android".

إصدار "استوديو Android"	إصدار AGP المطلوب
تحديث Narwhal الذي يتضمّن ميزات جديدة | 2025.1.2	4.0-8.12
Narwhal | 2025.1.1	‫3.2-8.11
تحديث Meerkat يحتوي على ميزات جديدة | 2024.3.2	‫3.2-8.10
Meerkat | 2024.3.1	‫3.2-8.9
تحديث Ladybug الذي يتضمّن ميزات جديدة | 2024.2.2	‫3.2 إلى 8.8
Ladybug | 2024.2.1	‫3.2-8.7
تحديث Koala Feature Drop | 2024.1.2	‫3.2-8.6
Koala | 2024.1.1	‫3.2-8.5
Jellyfish | 2023.3.1	‫3.2-8.4
Iguana | 2023.2.1	‫3.2 إلى 8.3
Hedgehog | 2023.1.1	‫3.2-8.2
Giraffe | 2022.3.1	3.2-8.1
Flamingo | 2022.2.1	‫3.2-8.0

إصدارات سابقة

إصدار "استوديو Android"	إصدار AGP المطلوب
Electric Eel | 2022.1.1	‫3.2-7.4
Dolphin | 2021.3.1	‫3.2-7.3
Chipmunk | 2021.2.1	‫3.2-7.2
Bumblebee | 2021.1.1	3.2-7.1
Arctic Fox | 2020.3.1	3.1-7.0

للحصول على معلومات عن الميزات الجديدة في المكوّن الإضافي لنظام Gradle المتوافق مع Android، يُرجى الاطّلاع على ملاحظات الإصدار الخاصة بالمكوّن الإضافي لنظام Gradle المتوافق مع Android.

الحد الأدنى لإصدارات الأدوات لمستوى واجهة برمجة تطبيقات Android

هناك حدّ أدنى لإصدارات Android Studio وAGP تتوافق مع مستوى معيّن من واجهة برمجة التطبيقات. قد يؤدي استخدام إصدارات أقدم من "استوديو Android" أو AGP مقارنةً بالإصدارات المطلوبة في targetSdk أو compileSdk لمشروعك إلى حدوث مشاكل غير متوقّعة. ننصح باستخدام أحدث إصدار مبكر حصري من "استوديو Android" وAGP للعمل على مشاريع تستهدف الإصدارات التجريبية من نظام التشغيل Android. يمكنك تثبيت إصدارات معاينة من Android Studio إلى جانب إصدار ثابت.

في ما يلي الحد الأدنى لإصدارات "استوديو Android" وAGP:

مستوى واجهة برمجة التطبيقات	أدنى إصدار من "استوديو Android"	الحد الأدنى لإصدار AGP
36.0	Meerkat | 2024.3.1 Patch 1	8.9.1
35	تحديث Koala Feature Drop | 2024.2.1	8.6.0
34	Hedgehog | 2023.1.1	8.1.1
33	Flamingo | 2022.2.1	7.2

تغييرات في نظام الإصدارات (تشرين الثاني/نوفمبر 2020)

نعمل على تعديل ترقيم الإصدارات للمكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) لكي يتطابق بشكلٍ أقرب مع أداة إنشاء Gradle الأساسية.

في ما يلي التغييرات البارزة:

• ستستخدم أداة AGP الآن التسمية الدلالية، وسيتم توجيه التغييرات الأساسية إلى الإصدارات الرئيسية.

• سيتم إصدار إصدار رئيسي واحد من AGP سنويًا، بما يتوافق مع الإصدار الرئيسي من Gradle.

• سيكون الإصدار التالي لـ AGP 4.2 هو الإصدار 7.0 وسيتطلب ترقية إلى الإصدار 7.x من Gradle. سيتطلّب كل إصدار رئيسي من AGP ترقية مهمة للإصدار في أداة Gradle الأساسية.

• وسيتم إيقاف واجهات برمجة التطبيقات نهائيًا قبل عام واحد تقريبًا، مع إتاحة وظائف بديلة في الوقت نفسه. ستتم إزالة واجهات برمجة التطبيقات المتوقّفة نهائيًا بعد عام واحد تقريبًا أثناء التحديث الكبير التالي.

التوافق

الحد الأقصى لمستوى واجهة برمجة التطبيقات الذي يتوافق معه الإصدار 8.10 من المكوّن الإضافي لنظام Gradle المتوافق مع Android هو المستوى 35. في ما يلي معلومات أخرى حول التوافق:

	الحد الأدنى للإصدار	الإصدار التلقائي	الملاحظات
Gradle	8.11.1	8.11.1	لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تحديث Gradle.
أدوات إنشاء حِزم SDK	35.0.0	35.0.0	ثبِّت أو ضبط أدوات إنشاء حِزم SDK.
NDK	لا ينطبق	27.0.12077973	ثبِّت أو ضبط إصدارًا مختلفًا من حزمة NDK.
JDK	17	17	لمزيد من المعلومات، يُرجى الاطّلاع على ضبط إصدار JDK.

التغييرات في واجهة برمجة التطبيقات

يحتوي الإصدار 8.10.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android على التغييرات البارزة التالية في واجهة برمجة التطبيقات:

• تغيير جذري على مستوى المصدر: يتطلب finalizeDsl الآن استخدام الأنواع المُستخدِمة للمَعلمات.

المشاكل التي تم إصلاحها

الإصدار 8.10.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

المشاكل التي تم إصلاحها
مكوّن إضافي لنظام Gradle المتوافق مع Android	المشكلة رقم 344016691 يجب أن يُعلن AGP أنّه متوافق مع الإصدار 35 من واجهة برمجة التطبيقات الذي سيتم طرحه قريبًا. المشكلة رقم 393189008 تعطُّل AndroidComponentsExtension.addSourceSetConfigurations عند تفعيل الإحصاءات المشكلة رقم 389951197 لا يمكن للمشروع ‎":app" الوصول إلى ‎"Project.group" و‎"Project.version" عند إعداد مشروع معزول في AGP 8.8.0 المشكلة رقم 394384907 نص الإعداد 'C:\Users\mypc\AppData\Local\Temp\ijresolvers2.gradle'، السطر 162 المشكلة رقم 394384907 نص الإعداد 'C:\Users\mypc\AppData\Local\Temp\ijresolvers2.gradle'، السطر 162 المشكلة رقم 353554169 تعذّر إزالة المحتوى من المكتبات التالية، وسيتم حزمها كما هي. المشكلة رقم 319065197 إضافة إمكانية تمرير معلومات "الفواصل المنعزلة" إلى R8 المشكلة رقم 390736538 تعطُّل التطبيق بسبب الخطأَين NoClassDefFoundError وClassNotFoundException عند تشغيل التطبيق من "استوديو Android" المشكلة رقم 395798193 المكوّن الإضافي لنظام Gradle المتوافق مع Android: تجنُّب إلغاء القيمة التلقائية للدالة Sync.getDestinationDir() في PackageRenderscriptTask وProcessJavaResTask المشكلة رقم 118690729 استخدام موارد Java المدمجة لاختبارات الوحدة الطلب رقم 400492927 مشروع معزول: خطأ في تسلسل نموذج DeclarativeSchema
Dexer (D8)	المشكلة رقم 401489623 Backporting of android.os.Build.VERSION_CODES_FULL incorrect for Baklava المشكلة رقم 401147877 لم يعُد إزالة الرمز البرمجي غير القابل للاستخدام في AutoClosable يُبلغ عن ExecutorService.close على أنّه متوافق.
Lint	المشكلة رقم 389023409 تحذير خطأ في أداة التدقيق بشأن التعليق التوضيحي `@Parcelize` على الواجهات المُغلقة المشكلة رقم 382396705 يتوقّف Android Studio 2024.3.1.4 عن العمل بشكل متقطع عند تعديل نصوص kotlin. المشكلة رقم 385394934 خطأ خاطئ في أداة التدقيق لـ CredentialManagerSignInWithGoogle المشكلة رقم 395836302 ConcurrentModificationException في فحص Aligned16KB lint المشكلة رقم 396584142 Lint: يؤدي AGP 8.10.0-alpha05 إلى ظهور الكثير من النتائج الموجبة الخاطئة لـ SyntheticAccessor المشكلة رقم 398807363 إتاحة تفعيل NewApi على مصادر الاختبار المشكلة رقم 396647876 ما هو تأثير الضغط على الزر "LintIdeFix" بعد فحص الرمز البرمجي في Android Studio؟ المشكلة رقم 399692455 خطأ في نص رسالة التحذير: "غير ضروري، لا يكون العنصر `Build.VERSION.SDK_INT >= Build.VERSION_CODES.O` صحيحًا *مطلقًا* هنا (يجب أن يكون `SDK_INT` أكبر من أو يساوي 26 وأقل من 31)"
Shrinker (R8)	المشكلة رقم 401546693 تعذّر إنشاء حزمة APK موقَّعة بعد التحديث إلى AGP 8.9.0 المشكلة رقم 397737234 تحليل السمة written-before-read في مواقع التخصيص يواجه خطأ عند إنشاء ملف classfile المشكلة رقم 389737060 مشكلة متعلّقة بواجهة برمجة التطبيقات Java SPI في أداة تصغير R8 للإصدارات 8.6.* 8.7.* 8.8.0 المشكلة رقم 401515589 ClassCastException من عملية تحويل آمنة في عملية إعداد الصف المشكلة رقم 404745556 مشكلة في تقليل حجم الموارد في AGP 8.9 تؤدي إلى عدم توفّر الموارد في وحدات الميزات الديناميكية المشكلة رقم 400746842 لا يمكن استدعاء com.android.tools.r8.internal.H5.x()

الإصدار 8.10.1 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

المشاكل التي تم إصلاحها
مكوّن إضافي لنظام Gradle المتوافق مع Android	المشكلة رقم 390602110 لا يؤدي تفعيل اختبارات الأجهزة بشكل صريح في نوع إصدار غير تلقائي باستخدام AGP إلى تحقيق النتيجة المطلوبة.
Shrinker (R8)	المشكلة رقم 406300397 NullPointerException عند تجميع تطبيق فوري بعد تحديث Kotlin إلى الإصدار 2.1.20 المشكلة رقم 406525499 [AGP]: ERROR: R8: java.lang.OutOfMemoryError: Required array length 2147483638 + 196 is too large