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

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

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

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

KotlinGroovy
plugins {
    id("com.android.application") version "8.9.0" apply false
    id("com.android.library") version "8.9.0" apply false
    id("org.jetbrains.kotlin.android") version "2.1.10" apply false
}
plugins {
    id 'com.android.application' version '8.9.0' apply false
    id 'com.android.library' version '8.9.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.1.10' apply false
}

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

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

تعديل Gradle

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

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

إصدار المكوِّن الإضافيالحد الأدنى لإصدار Gradle المطلوب
8.98.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
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.45.6.4 والإصدارات الأحدث
3.5.0 - 3.5.45.4.1 والإصدارات الأحدث
3.4.0 - 3.4.35.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.1 - 3.5
2.0.0 - 2.1.22.10 - 2.13
1.5.02.2.1 - 2.13
1.2.0 - 1.3.12.2.1 - 2.9
1.0.0 - 1.1.32.2.1 - 2.3

يمكنك تحديد إصدار Gradle في قائمة ملف > هيكل المشروع > المشروع في "استوديو Android"، أو يمكنك تعديل إصدار Gradle باستخدام سطر الأوامر. الطريقة المفضّلة هي استخدام أداة سطر الأوامر Gradle Wrapper التي تعدّل النصوص البرمجية gradlew. يضبط المثال التالي إصدار Gradle على 8.9 باستخدام Gradle Wrapper. يُرجى العلم أنّه عليك تنفيذ هذا الأمر مرّتين لترقية كلّ من Gradle و Gradle Wrapper نفسه (لمزيد من المعلومات، يُرجى الاطّلاع على ترقية Gradle Wrapper).

gradle wrapper --gradle-version 8.9

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

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

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

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

إصدار "استوديو Android" إصدار AGP المطلوب
Meerkat | 2024.3.1 ‫3.2-8.9
تحديث Ladybug الذي يتضمّن ميزات جديدة | 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" إصدار 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.9 من المكوّن الإضافي لـ Gradle في Android هو المستوى 35. في ما يلي معلومات أخرى حول التوافق:

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

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

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

المشاكل التي تم إصلاحها
مكوّن إضافي لنظام Gradle المتوافق مع Android
تقديم رسالة خطأ قابلة للتنفيذ عند تعذُّر مهمة إعداد GMD بسبب عدم توفّر مساحة كافية على القرص
لا يتعرّف المكوّن الإضافي com.android.settings على targetSdk
خطأ غير مفيد: "لم يتم تحديد compileSdkVersion. يُرجى إضافته إلى build.gradle".
عدم توفّر "الإنشاء من جديد" في قائمة "الإنشاء"
السماح لخدمة Kotlin المضمّنة في AGP بإضافة Dependency kotlin stdlib تلقائيًا
تعديل shouldConfigureKotlinPlatformAttribute للتعامل مع دعم kotlin المضمّن
تقديم بنية kotlin gradle في رسالة الخطأ لـ `checkTestedAppObfuscationRelease`
خطأ في "المكتبة المدمجة" عند توفّر إمكانية تحسين التبعية غير المحسّنة
لا يتم تمرير خصائص النظام من ملف gradle.properties إلى عمال R8 Gradle في عمليات منفصلة.
جعل BuiltArtifact.outputFile كنوع ملف
عدم توفير مساحة الاسم في المكتبة المدمجة لا يؤدي إلى ظهور رسالة خطأ مناسبة.
لا تسمح خيارات lint في الإصدار AGP 7.1.0-alpha08 بإخراج stdout
المكوّن الإضافي لنظام Gradle المتوافق مع Android: يجب أن تعرض الأسعار المتغيرة أسماء مجموعات المصادر
ذاكرة التخزين المؤقت للإعدادات غير ثابتة في ما يتعلق بإعداد متغيّر البيئة TERM
تعطُّل AndroidComponentsExtension.addSourceSetConfigurations عند تفعيل الإحصاءات
نص الإعداد 'C:\Users\mypc\AppData\Local\Temp\ijresolvers2.gradle'، السطر 162
تعطُّل AndroidComponentsExtension.addSourceSetConfigurations عند تفعيل الإحصاءات
Dexer (D8)
java.lang.VerifyError: Verifier rejected class: [0x430] copy1 v2<-v264 type=Undefined cat=3
Lint
تعطُّل أداة Lint عند إجراء عمليات الفحص في Lint gradle
تعذّر استخدام Lint بسبب InstantiationException بدون رسالة استثناء في تتبع تسلسل استدعاء الدوال البرمجية في Lint
نتيجة إيجابية خاطئة لفحص Lint: لا يتم منح إذن android.permission.SCHEDULE_EXACT_ALARM إلا لتطبيقات النظام
يجب تطبيق التحقّق من StringFormatInvalid على طريقة Compose stringResource
لا يعمل التعليق التوضيحي RequiresFeature مع ملفات Kotlin.
kotlin android.os.Handler removeCallbacks Runnable
خطأ WrongConstant في التعريف بدلاً من استخدام الثابت باستخدام shift
ظهور خطأ WrongConstant lint مرتين
استثناء وقت التشغيل في الإصدارات الأقدم من واجهة برمجة التطبيقات 26 مع واجهة برمجة التطبيقات Java nio غير المتوافقة (بدون خطأ lint)
أداة Lint تمنع استخدام RequiresApi حتى في طريقة المساعدة الخاصة في الاختبار
يعرض وضع K2 تحذيرًا بشأن RestrictedApi عند استخدام hasRoute(Route::class)‎ .في Android Studio
تقترح أداة Lint استبدال @RequiresExtension في الاختبار بـ @SdkSuppress، الذي لا يتوافق مع إضافات حزمة SDK.
يُبلغ Lint بشكلٍ غير صحيح عن تنسيق مُدمَج غير ضروري عند استخدام FrameLayout مع fitSystemWindows لتغليف RelativeLayout فرعي يتطلّب مساحة تمويه مخصّصة.
لا تراعي قاعدة التدقيق CoarseFineLocation سمة maxSdkVersion.
AppLinkSplitToWebAndCustom is UnknownIssue in lint 8.7.3
تحقّق Lint من تعطُّل StringEscapeDetector عند "‎\\ "
تحذير خطأ في أداة التدقيق بشأن التعليق التوضيحي `@Parcelize` على الواجهات المُغلقة
يتوقّف Android Studio 2024.3.1.4 عن العمل بشكل متقطع عند تعديل نصوص kotlin.
دمج Lint
لا يتم تشغيل lintVitalRelease تلقائيًا عند إنشاء حِزمة التطبيق
Shrinker (R8)
لا يعمل Gson proguard بشكلٍ صحيح بعد الترقية إلى AGP 8.8
java.lang.VerifyError: Verifier rejected class
يتعطل Leanback عند تصغيره باستخدام R8 المضمّن في AGP 8.10.0-alpha04