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

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

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

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

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

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

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

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

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

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

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

Kotlin

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

رائع

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

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

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

تعديل Gradle

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

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

إصدار المكوِّن الإضافيالحد الأدنى المطلوب لإصدار Gradle
8.4 (إصدار أولي)نموذج 8.6-rc-1
8.38.4
8.28.2
8.1من نظام التشغيل Android
من نظام التشغيل Androidمن نظام التشغيل Android
7.47.5

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

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

gradle wrapper --gradle-version 8.3

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

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

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

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

إصدار "استوديو Android" إصدار AGP المطلوب
قنديل البحر | 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
Electric eel | 2022.1.1 3.2-7.4

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

إصدار "استوديو Android" إصدار AGP المطلوب
دولفين | 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.4 8.4 لمزيد من المعلومات، يمكنك الاطّلاع على تحديث Gradle.
أدوات إنشاء حِزم تطوير البرامج (SDK) 34.0.0 34.0.0 ثبِّت أو ضبط أدوات إصدار SDK.
العُقدة (NDK) لا ينطبق 25.1.8937393 ثبِّت أو اضبط نسخة مختلفة من NDK.
JDK 17 17 للاطلاع على مزيد من المعلومات، راجع إعداد إصدار JDK.

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

إصدارات التصحيح

في ما يلي قائمة بإصدارات التصحيح في الإصدار Android Studio Iguana والإصدار 8.3 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.

Android Studio Iguana | 2023.2.1 التصحيح 1 وAGP 8.3.1 (آذار/مارس 2024)

يتضمّن هذا التحديث الثانوي هذه إصلاحات الأخطاء.

دعم كتالوجات إصدارات Gradle

يتوافق "استوديو Android" مع ميزة Gradle Version Catalogs المستندة إلى لغة TOML، وهي ميزة تتيح لك إدارة التبعيات في موقع مركزي واحد ومشاركة التبعيات في الوحدات أو المشاريع. يساعد "استوديو Android" الآن في تسهيل عملية ضبط كتالوجات الإصدارات من خلال اقتراحات المحرّرين والدمج مع مربّع حوار بنية المشروع. تعرَّف على كيفية إعداد ميزة Gradle Version Catalogs وضبطها أو كيفية نقل إصدارك إلى كتالوجات الإصدارات.

إكمال الرمز والتنقل

يتيح "استوديو Android" إمكانية إكمال الرمز عند تعديل كتالوج الإصدار بتنسيق ملف TOML أو إضافة تبعية من كتالوج الإصدار إلى ملف إصدار. لاستخدام إكمال الرمز، اضغط على Ctrl+Space (Command+Space على نظام التشغيل macOS). بالإضافة إلى ذلك، يمكنك الانتقال بسرعة من مرجع التبعية في ملف build.gradle في تطبيقك إلى المكان الذي تم تعريفه به في كتالوج الإصدارات بالضغط على Ctrl+b (Command+b على نظام التشغيل macOS).

إكمال التعليمة البرمجية عند إضافة تبعية

الدمج مع مربّع حوار "بنية المشروع"

إذا كان مشروعك يستخدم كتالوج إصدارات محدّد بتنسيق ملف TOML، يمكنك تعديل المتغيرات التي حدّدتها من خلال مربّع الحوار بنية المشروع في قسم عرض المتغيّرات (ملف > بنية المشروع > المتغيرات) في Android Studio. لكل كتالوج إصدار، توجد قائمة منسدلة تسرد المتغيرات من هذا الكتالوج. لتعديل متغيّر، انقر على قيمته واستبدله. عند حفظ هذه التغييرات، يتم تحديث ملف TOML وفقًا لذلك.

المتغيّرات من كتالوج الإصدارات في مربّع الحوار "بنية المشروع"

يمكنك أيضًا تعديل التبعيات في عرض مربع الحوار بنية المشروع التبعيات (ملف > بنية المشروع > التبعيات). لتحديث الإصدارات باستخدام مربع الحوار بنية المشروع، انتقِل إلى الوحدة والتبعية التي تريد تعديلها، ثم حدِّث حقل الإصدار المطلوب. وعند حفظ هذه التغييرات، يتم تعديل ملف TOML وفقًا لذلك. لاحظ أنه إذا تم تحديد إصدار التبعية باستخدام متغير، فإن تحديث الإصدار بهذه الطريقة يؤدي مباشرةً إلى استبدال المتغير بقيمة غير قابلة للتغيير. وتجدر الإشارة أيضًا إلى أن إزالة التبعية من ملف الإصدار، سواء كنت تستخدم مربع الحوار بنية المشروع أم لا، لا يؤدي إلى إزالة التبعية من كتالوج الإصدارات.

التبعيات من كتالوج الإصدار في مربع الحوار "بنية المشروع"

القيود والمشاكل المعروفة

في ما يلي المشاكل أو القيود المعروفة المتعلّقة بتوافق كتالوجات إصدار Gradle في "استوديو Android":

  • حدث خطأ أثناء تمييز إعلانات الأسماء المستعارة للمكوّنات الإضافية في ملفات نصوص Kotlin البرمجية: عند إضافة تعريف مكوّن إضافي للنموذج alias(libs.plugins.example)، يضيف المحرِّر خطًا أحمر تحت الجزء libs. هذه مشكلة معروفة في الإصدارات 8.0 من Gradle والإصدارات الأقدم، وسيتم حلّها في إصدار مستقبلي من Gradle.

  • لا يتوافق "استوديو Android" إلا مع كتالوجات الإصدارات بتنسيق TOML: في الوقت الحالي، لا يتوفّر دعم "إكمال الرمز البرمجي لـ "استوديو Android" والتنقل و"بنية المشروع" إلا لكتالوجات الإصدارات المحدّدة بتنسيق ملف TOML. مع ذلك، سيظل بإمكانك إضافة كتالوج الإصدارات مباشرةً في ملف settings.gradle واستخدام العناصر الاعتمادية الخاصة به في مشروعك.

  • التنقل في ملفات إصدار KTS غير متاح: الانتقال إلى تعريف التبعية في كتالوج الإصدار باستخدام Control+النقر (Command+النقر على نظام التشغيل macOS) غير متاح حتى الآن لملفات الإصدار المكتوبة باستخدام نص Kotlin البرمجي.

  • يضيف "مساعد Firebase" التبعيات مباشرةً في النصوص البرمجية للإصدارات: يضيف مساعد Firebase التبعيات مباشرةً إلى النصوص البرمجية للإصدار، بدلاً من كتالوجات الإصدارات.

  • وظيفة "البحث عن الاستخدامات" غير متاحة: لا تتوفر بعد إمكانية العثور على الاستخدامات لمتغير كتالوج الإصدار في ملفات الإصدار الأخرى، سواء كان ملف الإصدار بتنسيق KTS أو Groovy. وهذا يعني أنّ استخدام Control+النقر (Command+النقر على نظام التشغيل macOS) على تعريف متغيّر في كتالوج الإصدارات لا يؤدي إلى ملفات الإصدار التي يُستخدَم فيها المتغيّر.

  • يعرض مربّع حوار "بنية المشروع" في "استوديو Android" عدة ملفات كتالوج إذا كانت في مجلد gradle الجذر، ولكنها لا تعرض كتالوجات لإصدار مركب. على سبيل المثال، إذا كان لديك ملفا كتالوج - أحدهما لتطبيقك والآخر لإصدار مركب - فإن مربع حوار "بنية المشروع" يعرض ملف كتالوج التطبيق فقط. يمكنك استخدام تصميم مركب، ولكن عليك تعديل ملف TOML مباشرةً.

إحصاءات إضافية عن حِزم SDK: المشاكل المتعلّقة بالسياسات

يعرض "استوديو Android" تحذيرات من الوبر في ملفَي build.gradle.kts وbuild.gradle، وفي مربع حوار بنية المشروع لحِزم تطوير البرامج (SDK) المتاحة للجميع التي تنتهك سياسات Play في أداة Google Play SDK Index. ويجب تعديل أي تبعيات تنتهك سياسات Play لأنّ هذه الانتهاكات قد تمنعك من النشر على Google Play Console في المستقبل. وتُكمِّل التحذيرات بشأن انتهاك السياسة تحذيرات بشأن الإصدارات القديمة التي يعرضها "استوديو Android".

إتاحة إصدار Compesdk من استوديو Android

يعرض "استوديو Android" تحذيرًا إذا كان مشروعك يستخدم compileSdk غير متوافق مع الإصدار الحالي من "استوديو Android". وتقترح الأداة أيضًا الانتقال إلى إصدار من "استوديو Android" يتوافق مع compileSdk الذي يستخدمه مشروعك. يُرجى العلم أنّ ترقية "استوديو Android" قد تتطلّب أيضًا ترقية AGP. يعرض AGP أيضًا تحذيرًا في نافذة أداة إنشاء إذا كان الإصدار الحالي من AGP غير متوافق مع compileSdk الذي يستخدمه مشروعك.

تغييرات في سلوك الوبر

بدءًا من الإصدار 8.3.0-alpha02 من المكوّن الإضافي لنظام Gradle المتوافق مع Android، عند تشغيل أداة Lint على إحدى الوحدات، يتم تنفيذ مهام تحليل الوبر المنفصلة للمكوّنات الرئيسية ومكوّنات الاختبار للوحدة. السبب في هذا التغيير هو تحسين الأداء. للعودة إلى السلوك السابق، يجب ضبط android.experimental.lint.analysisPerComponent=false في ملف gradle.properties.

تصغير الموارد بدقة وبشكل تلقائي

يتم تلقائيًا تفعيل ميزة "التصغير الدقيق للموارد" التي تزيل الإدخالات غير المستخدَمة من ملف resources.arsc وتزيل ملفات الموارد غير المستخدَمة. عند تفعيل عملية التقليص هذه، يتم تقليل جدول الموارد ولا يتم تضمين سوى إدخالات مجلد res المشار إليها في حزمة APK.

لإيقاف التصغير الدقيق للموارد، اضبط android.enableNewResourceShrinker.preciseShrinking على false في ملف gradle.properties الخاص بالمشروع.