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

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

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

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

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

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

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

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

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

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

Kotlin

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

Groovy

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

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

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

تعديل Gradle

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

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

إصدار المكوّن الإضافيالحد الأدنى لإصدار Gradle المطلوب
8.138.13
‫8.128.13
8.118.13
8.10‫8.11.1
8.9‫8.11.1
8.88.10.2
8.78.9
8.68.7
8.58.7
8.48.6
8.38.4
8.28.2
‫8.1من نظام التشغيل Android
من نظام التشغيل Androidمن نظام التشغيل Android

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

إصدار المكوّن الإضافيإصدار Gradle المطلوب
7.47.5
‫7.37.4
‫7.2‫7.3.3
‫7.1‫7.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.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.13 باستخدام أداة Gradle Wrapper. يُرجى العِلم أنّه عليك تنفيذ هذا الأمر مرّتين لترقية كل من Gradle وGradle Wrapper (لمزيد من المعلومات، اطّلِع على ترقية Gradle Wrapper). 

gradle wrapper --gradle-version 8.13

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

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

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

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

إصدار Android Studio إصدار AGP المطلوب
تحديث Narwhal 4 | 2025.1.4 ‫4.0-8.13
تحديث Narwhal 3 | 2025.1.3 ‫4.0-8.13
تحديث Narwhal Feature Drop‏ | 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 Feature Drop‏ | 2024.2.2 ‫3.2-8.8
Ladybug | 2024.2.1 ‫3.2-8.7
تحديث "ميزات كوالا" | 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 Studio إصدار 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" وAGP تتوافق مع مستوى معيّن من واجهة برمجة التطبيقات. قد يؤدي استخدام إصدارات أقدم من "استوديو Android" أو المكوّن الإضافي لنظام Gradle المتوافق مع Android مقارنةً بالإصدارات التي يتطلبها ملف targetSdk أو compileSdk في مشروعك إلى حدوث مشاكل غير متوقّعة. ننصحك باستخدام أحدث إصدار مبكر حصري من "استوديو Android" و"المكوّن الإضافي لنظام Gradle المتوافق مع Android" للعمل على المشاريع التي تستهدف إصدارات مبكرة حصرية من نظام التشغيل Android. يمكنك تثبيت إصدارات معاينة من "استوديو Android" إلى جانب إصدار ثابت.

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

مستوى واجهة برمجة التطبيقات أدنى إصدار من "استوديو Android" الحد الأدنى لإصدار "مكوّن Android الإضافي لنظام Gradle"
36.1 تحديث Narwhal 3 | 2025.1.3 ‫8.13.0
36.0 Meerkat | 2024.3.1 Patch 1 ‫8.9.1
35 تحديث "كوالا" | 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 الآن نظام تحديد الإصدارات الدلالي، وسيتم استهداف التغييرات غير المتوافقة مع الإصدارات الرئيسية.

  • سيتم طرح إصدار رئيسي واحد من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" كل عام، بما يتوافق مع الإصدار الرئيسي من Gradle.

  • سيكون الإصدار الذي يلي الإصدار 4.2 من "مكوّن Android الإضافي لبرنامج Gradle" هو الإصدار 7.0، وسيتطلّب الترقية إلى الإصدار 7.x من Gradle. سيتطلّب كل إصدار رئيسي من "مكوّن Android الإضافي في Gradle" ترقية الإصدار الرئيسي في أداة Gradle الأساسية.

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

التوافق

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

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

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

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

المشاكل التي تم إصلاحها
المكوّن الإضافي لنظام Gradle المتوافق مع Android
تنفيذ CheckAarMetadataTask في مشاريع المكتبة عند إنشاء ملف AAR
لا يمكن لمكوّن Fused Library الإضافي معالجة مراجع الموارد من مكتبة خارجية
يجب أن يسمح مكوّن Fused Library الإضافي باستخدام overrideLibrary
تغيير القيمة التلقائية لـ targetSdk لتستند إلى compileSdk بدلاً من minSdk
تعطُّل `com.android.kotlin.multiplatform.library` عند استخدام الأجهزة المُدارة من Gradle
Shrinker (R8)
ClassCastException من فئة غير ممكنة باستخدام R8
ArrayIndexOutOfBoundsException: الفهرس 0 خارج الحدود للطول 0 منذ الإصدار 8.10.0
يكون تحليل الأنماط في واجهة برمجة التطبيقات enableExperimentalPartialShrinking صارمًا جدًا