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

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

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

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

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

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

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

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

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

لمزيد من المعلومات حول نظام تصميم Gradle، راجِع دليل مستخدم Gradle.

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

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

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

Kotlin

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

رائع

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

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

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

تعديل Gradle

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

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

إصدار المكوِّن الإضافي	الحد الأدنى المطلوب لإصدار Gradle
8.4	8.6
8.3	8.4
8.2	8.2
8.1	من نظام التشغيل Android
من نظام التشغيل Android	من نظام التشغيل Android
7.4	7.5

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

إصدار المكوِّن الإضافي	إصدار Gradle المطلوب
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 إلى 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.4 باستخدام Gradle Wrapper. ملاحظة: تحتاج إلى تشغيل هذا الأمر مرتين لترقية كل من Gradle و"Gradle Wrapper" (التفاف النص) نفسه (لمزيد من المعلومات، يُرجى مراجعة ترقية Gradle Wrapper).

gradle wrapper --gradle-version 8.4

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

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

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

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

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

إصدار "استوديو Android"	إصدار AGP المطلوب
كوالا | 2024.1.1	3.2-8.5
قنديل البحر | 2023.3.1	3.2-8.4
الإغوانا | 1 تشرين الثاني (نوفمبر) 2023	3.2-8.3
القنفذ | 1.1.2023	3.2 إلى 8.2
زرافة | 1 حزيران (يونيو) 2022	8.1-3.2
طائر الفلامينغو | 1 تشرين الثاني (نوفمبر) 2022	3.2-8.0

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

إصدار "استوديو Android"	إصدار AGP المطلوب
Electric eel | 2022.1.1	3.2-7.4
دولفين | 2021/3.1	3.2-7.3
سنجاب | 2021.2.1	7.2-3.2
Bumblebee | 2021.1.1	3.2-7.1
Arctic Fox | 2020.3.1	من 3.1 إلى 7.0

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

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

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

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

مستوى واجهة برمجة التطبيقات	الحد الأدنى لإصدار "استوديو Android"	الحد الأدنى لإصدار AGP
معاينة VanillaIceCream	قنديل البحر | 2023.3.1	8.4
34	القنفذ | 1.1.2023	8.1.1
33	طائر الفلامينغو | 1 تشرين الثاني (نوفمبر) 2022	7.2

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

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

في ما يلي أهم التغييرات:

• سيستخدم AGP الآن الإصدارات الدلالية، وسيتم استهداف أي تغييرات قد تؤدي إلى تعطُّل في الإصدارات الرئيسية.

• وسيتم طرح إصدار رئيسي واحد من AGP سنويًا، يتماشى مع إصدار Gradle الرئيسي.

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

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

التوافق

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

	الحد الأدنى للإصدار	الإصدار التلقائي	Notes
مبرّد	8.6	8.6	لمزيد من المعلومات، يمكنك الاطّلاع على تحديث Gradle.
أدوات إنشاء حِزم تطوير البرامج (SDK)	34.0.0	34.0.0	ثبِّت أو ضبط أدوات إصدار SDK.
العُقدة (NDK)	لا ينطبق	26.1.10909125	ثبِّت أو اضبط نسخة مختلفة من NDK.
JDK	17	17	للاطلاع على مزيد من المعلومات، راجع إعداد إصدار JDK.

في ما يلي الميزات الجديدة في الإصدار 8.4 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.

تم تصغير صفوف المكتبة

بدءًا من الإصدار 8.4 من المكوّن الإضافي لنظام Gradle المتوافق مع Android، إذا تم تصغير مشروع مكتبة Android، سيتم نشر صفوف البرامج القصيرة لنشرها بين المشاريع. وهذا يعني أنّه إذا كان التطبيق يعتمد على الإصدار الذي تم تقليصه من المشروعات الفرعية لمكتبة Android، ستتضمّن حزمة APK صفوف مكتبة Android محدودة. وقد تحتاج إلى تعديل قواعد إبقاء المكتبة في حال عدم توفّر فئات في حزمة APK.

إذا كنت تنشئ وتنشر AAR، سيتم تضمين الأواني التي تعتمد عليها مكتبتك بدون تقليصها في AAR، ما يعني أنّ أداة تقليص الرموز لن تعمل عليها.

للعودة إلى السلوك السابق، اضبط android.disableMinifyLocalDependenciesForLibraries في ملف gradle.properties وأبلغ عن الخطأ. وستزيل الإصدارات المستقبلية من AGP هذه العلامة.