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

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

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

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

توضّح هذه الصفحة كيفية إبقاء أدوات 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.11.0 من الملف build.gradle.kts:

Kotlin

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

Groovy

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

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

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

تعديل Gradle

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

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

إصدار المكوّن الإضافي	الحد الأدنى المطلوب من إصدار Gradle
8.11	8.13
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.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"

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

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

إصدار Android Studio	إصدار AGP المطلوب
تحديث 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
تحديث 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 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 Studio وAGP تتوافق مع مستوى معيّن من واجهة برمجة التطبيقات. قد يؤدي استخدام إصدارات أقدم من "استوديو Android" أو "مكوّن Android الإضافي في Gradle" من الإصدارات المطلوبة في targetSdk أو compileSdk لمشروعك إلى حدوث مشاكل غير متوقّعة. ننصحك باستخدام أحدث إصدار مبكر حصري من "استوديو Android" وAGP للعمل على المشاريع التي تستهدف إصدارات مبكرة حصرية من نظام التشغيل Android. يمكنك تثبيت إصدارات معاينة من "استوديو Android" إلى جانب إصدار ثابت.

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

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

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

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

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

التوافق

الحدّ الأقصى لمستوى واجهة برمجة التطبيقات الذي يتوافق معه الإصدار 8.1.1 من المكوّن الإضافي لنظام 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.1.1 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

المشاكل التي تم إصلاحها
المكوّن الإضافي لنظام Gradle المتوافق مع Android	المشكلة رقم 400492927 مشروع معزول: خطأ في تسلسل DeclarativeSchemaModel المشكلة رقم ‎327770434 طلب: بشأن إيقاف zipAlignEnabled نهائيًا، يُرجى توضيح سبب إيقافها وما هو البديل الذي يمكن استخدامه المشكلة رقم 406464766 [الإصدار 8.9.0 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" والإصدارات الأحدث] إتاحة BuiltinKotlinCompilation لجميع المكوّنات الإضافية لمترجم Kotlin المشكلة رقم 405419218 تحديث تبعيات Kotlin إلى الإصدار 2.1.20 عند إنشاء الإصدار 8.11 من "مكوّن Android الإضافي في Gradle" المشكلة رقم 372269616 عدم فرض com.android.internal.version-check عند تعديل توزيع Gradle المشكلة رقم 294183018 تعذُّر الإنشاء عند عدم توفّر ملف Proguard
Dexer (D8)	المشكلة رقم 418143856 تعطُّل عملية إزالة التشويش عن AutoClosable في إصدارات AGP من داخل "استوديو Android"
Lint	المشكلة رقم 343347272 لا ترصد قاعدة Lint BuildListAdds استخدام الدالة operator fun plusAssign (‎+=) في buildList المشكلة رقم 399428893 استخدام UseSdkSuppress للحالات الموجبة الخاطئة في رمز أداة الاختبار المساعدة المشكلة رقم 398924424 التحذير من تعارض محتمل بين العضوية والإضافة المشكلة رقم 406935594 نتيجة إيجابية خاطئة لمشكلة Lint‏ `MemberExtensionConflict` إذا كان مستقبل دالة الإضافة يقبل القيم الخالية المشكلة رقم 405442664 نتيجة موجبة خاطئة لفحص `WrongGradleMedthod` المشكلة رقم 405654866 نتيجة إيجابية خاطئة لـ SyntheticAccessor عند استدعاء عضو اصطناعي لفئة البيانات المشكلة رقم 406739378 الخطأ TestMode.SUPPRESSIBLE للمشكلة التي تم الإبلاغ عنها في تعبير قابل للتصنيف المشكلة رقم 406991279 New MemberExtensionConflict lint issues starting in AGP 8.11.0-alpha03 - how to solve? المشكلة رقم 409716542 يشير فحص Lint في ملف libs.versions.toml إلى الترقية إلى إصدار غير متوافق من "مكوّن Android الإضافي".
Shrinker (R8)	المشكلة رقم 402800800 تعذُّر إنشاء حِزمة AAB موقَّعة بعد التحديث إلى الإصدار 8.9.0 من "مكوّن Android الإضافي في Gradle" المشكلة رقم 418568424 تعطُّل R8 مع الإصدار 24 من min-api عند معالجة رمز JavaFuzzer

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

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