تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

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

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

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

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

Kotlin

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

رائع

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

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

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

تعديل Gradle

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

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

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

gradle wrapper --gradle-version 8.7

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

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

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

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

إصدار "استوديو Android"	إصدار AGP المطلوب
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
معاينة Baklava	Meerkat \| 2024.3.1	8.9.0
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.6 من المكوّن الإضافي لنظام Gradle المتوافق مع Android هو المستوى 34. في ما يلي معلومات أخرى حول التوافق:

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

تغيير في سلوك Lint

بدءًا من الإصدار 8.7.0-alpha08 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android"، إذا كان هناك LintError عند تشغيل أداة lint باستخدام Gradle، تُرسِل مهمة تحليل lint استثناءً. يمنع هذا التغيير تخزين الأخطاء النادرة في ذاكرة التخزين المؤقت للإصدار.

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

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

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

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

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

المشكلة رقم 344016691

يجب أن يُعلن AGP أنّه متوافق مع الإصدار 35 من واجهة برمجة التطبيقات الذي سيتم طرحه قريبًا.

المشكلة رقم 355397971

AGP 8.5: يتم تنفيذ المزيد من مهام "mergeDebugResources"، ما يؤدي إلى إبطاء عمليات الإنشاء

المشكلة رقم 353579998

اجعل ndk 27 هو حزمة NDK التلقائية في AGP.

المشكلة رقم 344016691

يجب أن يُعلن AGP أنّه متوافق مع الإصدار 35 من واجهة برمجة التطبيقات الذي سيتم طرحه قريبًا.

المشكلة رقم 344016691

يجب أن يُعلن AGP أنّه متوافق مع الإصدار 35 من واجهة برمجة التطبيقات الذي سيتم طرحه قريبًا.

المشكلة رقم 230685896

تعذّر تشغيل أداة Android lint بسبب NoSuchFileException

المشكلة رقم 307784512

تنسخ دالة BuildType#initWith كتلة المعالجة اللاحقة ولكن لا يتم تطبيق إعدادات Proguard.

المشكلة رقم 359245746

لا يمكن دمج علامات foregroundServiceType

المشكلة رقم 230685896

تعذّر تشغيل أداة Android lint بسبب NoSuchFileException

Lint

المشكلة رقم 36981231

من المفترض أن تتحقّق أداة Lint من العناصر غير الصالحة المستخدَمة كمجموعات عرض.

الطلب رقم 62810553

"سمة android:host غير متوفّرة" لمعرّفات الموارد المنتظمة التي تحتوي على مضيف غير صالح

المشكلة رقم 360840930

عدم توافق KtAnalysisSessionProvider مع عمليات التحقّق من الأخطاء في التنقيح التي تمّ تقديمها في الإصدار 8.7.0-alpha04

المشكلة رقم 364261817

"نتيجة إيجابية خاطئة" لـ WrongConstant عند استخدام PackageManager.ResolveInfoFlags.of مع Kotlin

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

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

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

المشكلة رقم 364967835

تحتوي مستندات agp على الكثير من العناصر التي لم يتم تحديدها بعد.

Lint

المشكلة رقم 367752734

AGP 8.6.1: انحدار - تعذُّر فحص WrongConstant باستخدام [Int].toLong() داخل @LongDef في Kotlin

المشكلة رقم 365376495

خطأ lint "يجب تحديد مضيف واحد على الأقل" عند ضبط مخطّط فلتر الغرض http أو https

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

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

Lint

المشكلة رقم 370694831

AGP 8.7.0 - Lint False Positive RestrictedApi on NavOptionsBuilder.popUpTo

Shrinker (R8)

المشكلة رقم 363492038

[R8 8.6.27] تم استبدال تنفيذ الطريقة بـ `throw null`

المشكلة رقم 372749733

تُصدر ملفات Proguard التلقائية لنظام التشغيل Android تحذيرًا عند استخدامها مع الإصدار الحالي من R8.

المشكلة رقم 370937458

يؤدي MissingStartupProfileItemsDiagnostic إلى تعطُّل برنامج Gradle العميل بخطأ "تعذُّر توفُّر ذاكرة" إذا كانت الرسالة كبيرة جدًا.

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

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

Lint

المشكلة رقم 374488858

عدم توفّر العديد من التحذيرات بشأن طرق واجهة برمجة التطبيقات لتحليل الأخطاء عند تشغيل أداة التدقيق

المشكلة رقم 375352607

نتيجة إيجابية خاطئة لفحص Lint: لا يتم منح إذن android.permission.SCHEDULE_EXACT_ALARM إلا لتطبيقات النظام