يستند نظام تصميم "استوديو 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"، قد تظهر لك رسالة تطلب منك تحديث المكوّن الإضافي لنظام Gradle المتوافق مع Android تلقائيًا إلى أحدث إصدار متاح. يمكنك اختيار قبول التعديل أو تحديد إصدار يدويًا استنادًا إلى متطلبات الإصدار الخاصة بمشروعك.
يمكنك تحديد إصدار المكوِّن الإضافي في قائمة ملف > بنية المشروع > مشروع في "استوديو Android"، أو ملف build.gradle.kts ذي المستوى الأعلى. ينطبق إصدار المكوِّن الإضافي على جميع الوحدات التي تم إنشاؤها في مشروع "استوديو Android" هذا. ويضبط المثال التالي المكوِّن الإضافي على الإصدار 8.4.0 من ملف build.gradle.kts:
Kotlin
plugins {
id("com.android.application") version "8.4.0" apply false
id("com.android.library") version "8.4.0" apply false
id("org.jetbrains.kotlin.android") version "1.9.23" apply false
}
رائع
plugins {
id 'com.android.application' version '8.4.0' apply false
id 'com.android.library' version '8.4.0' apply false
id 'org.jetbrains.kotlin.android' version '1.9.23' apply false
}
تنبيه: يجب عدم استخدام التبعيات الديناميكية في أرقام الإصدارات، مثل 'com.android.tools.build:gradle:8.4.+'.
وقد يؤدي استخدام هذه الميزة إلى إجراء تحديثات غير متوقّعة للإصدار وحدوث صعوبة
في حلّ الاختلافات في الإصدارات.
إذا لم يتم تنزيل إصدار المكوّن الإضافي المحدَّد، تنزِّله Gradle في المرة التالية التي تنشئ فيها مشروعك، أو انقر على File (ملف) > Sync Project with Gradle Files (مزامنة المشروع مع ملفات Gradle) من شريط القوائم في "استوديو Android".
تعديل Gradle
عند تحديث "استوديو Android"، قد تظهر لك رسالة تطلب منك أيضًا تحديث تطبيق Gradle إلى آخر إصدار متاح. يمكنك اختيار قبول التحديث أو تحديد إصدار يدويًا استنادًا إلى متطلبات الإصدار الخاصة بمشروعك.
يسرد الجدول التالي إصدار Gradle المطلوب لكل إصدار من المكوّن الإضافي لنظام Gradle المتوافق مع Android. للحصول على أفضل أداء، يجب عليك استخدام أحدث إصدار ممكن من كل من Gradle والمكون الإضافي.
| إصدار المكوِّن الإضافي | الحد الأدنى المطلوب لإصدار Gradle |
|---|---|
| 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 | من 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.4 باستخدام Gradle Wrapper.
تجدر الإشارة إلى أنّك تحتاج إلى تشغيل هذا الأمر مرّتَين لترقية كلّ من Gradle
وأداة Gradle Wrapper نفسها (لمزيد من المعلومات، يُرجى الاطّلاع على
ترقية ملف Gradle Wrapper).
gradle wrapper --gradle-version 8.4
وقد يتعذّر ذلك في بعض الحالات، على سبيل المثال إذا كنت قد حدّثت AGP الآن
ولم يعُد متوافقًا مع إصدار Gradle الحالي. في هذه الحالة،
تحتاج إلى تعديل مرجع توزيع Gradle في
ملف gradle/wrapper/gradle-wrapper.properties. ويضبط المثال التالي إصدار Gradle على 8.4 في ملف gradle-wrapper.properties.
...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.4-bin.zip
...
المكوّن الإضافي لنظام Gradle المتوافق مع Android والتوافق مع Android Studio
يستند نظام تصميم "استوديو Android" إلى منصّة Gradle، بينما يضيف المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) العديد من الميزات الخاصة بإنشاء تطبيقات Android. يسرد الجدول التالي إصدار AGP المطلوب لكل إصدار من إصدارات "استوديو Android".
| إصدار "استوديو Android" | إصدار AGP المطلوب |
|---|---|
| كوالا | 1.1.2024 | 8.5-3.2 |
| قنديل البحر | 2023.3.1 | 8.4-3.2 |
| الإغوانا | 2023.2.1 | 3.2-8.3 |
| القنفذ | 2023.1.1 | من 3.2 إلى 8.2 |
| الزرافة | 2022.3.1 | من 3.2 إلى 8.1 |
| فلامينغو | 2022.2.1 | من 3.2 إلى 8.0 |
إصدارات سابقة
| إصدار "استوديو Android" | إصدار AGP المطلوب |
|---|---|
| Electric Eel | 2022.1.1 | 3.2-7.4 |
| دولفين | 2021.3.1 | 3.2-7.3 |
| سنجاب | 2021.2.1 | 3.2-7.2 |
| Bumblebee | 1.1.2021 | 3.2-7.1 |
| الثعلب القطبي | 2020.3.1 | من 3.1 إلى 7.0 |
للحصول على معلومات بشأن الميزات الجديدة في المكوّن الإضافي لنظام Gradle المتوافق مع Android، يمكنك الاطّلاع على ملاحظات إصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android.
الحد الأدنى من إصدارات الأدوات لمستوى واجهة برمجة تطبيقات Android
هناك حد أدنى من إصدارات "استوديو Android" وAGP تتوافق مع مستوى محدّد من واجهة برمجة التطبيقات. قد يؤدي استخدام إصدارات Android Studio أو AGP من الإصدار المطلوب في targetSdk أو compileSdk لمشروعك إلى حدوث مشاكل غير متوقَّعة. ننصح باستخدام أحدث إصدار معاينة من "استوديو Android" وAGP للعمل على المشاريع التي تستهدف إصدارات المعاينة من نظام التشغيل Android. يمكنك تثبيت إصدارات معاينة من "استوديو Android" إلى جانب إصدار ثابت.
في ما يلي الحد الأدنى لإصدارات "استوديو Android" وAGP:
| مستوى واجهة برمجة التطبيقات | الحدّ الأدنى لإصدار "استوديو Android" | الحد الأدنى لإصدار AGP |
|---|---|---|
| معاينة VanillaIceCream | قنديل البحر | 2023.3.1 | 8.4 |
| 34 | القنفذ | 2023.1.1 | 8.1.1 |
| 33 | فلامينغو | 2022.2.1 | 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.6 | 8.6 | لمعرفة المزيد من المعلومات، يمكنك الاطّلاع على تحديث Gradle. |
| أدوات إنشاء حِزم تطوير البرامج (SDK) | 34.0.0 | 34.0.0 | تثبيت أدوات إنشاء حزمة تطوير البرامج (SDK) أو ضبطها |
| كرونة دنماركية | لا ينطبق | 26.1.10909125 | تثبيت أو ضبط إصدار مختلف من NDK. |
| JDK | 17 | 17 | لمزيد من المعلومات، راجِع إعداد إصدار JDK. |
في ما يلي الميزات الجديدة في الإصدار 8.4 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.
إصدارات التصحيح
في ما يلي قائمة بإصدارات التصحيح في الإصدار 8.4 من المكوّن الإضافي لنظام Gradle المتوافق مع Android Studio والإصدار 8.4 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.
Android Studio Jellyfish | التصحيح 2 لعام 2023.3.1 والإصدار 8.4.2 من AGP (حزيران/يونيو 2024)
تحديث أمان مهمّ: قد تؤدي ثغرة أمنية في مكوّن GitHub الإضافي والمتوفّر في "استوديو Android" Iguana | الإصدار 2023.2.1 والإصدارات الأحدث إلى الكشف عن رموز الدخول لجهات غير مصرّح بها.
الحل: نجح Jetbrains في حلّ المشكلة في منتجات النظام الأساسي IntelliJ، وأصبح الحلّ متوفرًا الآن في Android Studio Jellyfish | الإصدار 2023.3.1 Patch 2 (2023.3.1.20).
إذا كان لديك إصدار "استوديو Android" على القناة الثابتة، يمكنك الحصول على التحديث من خلال النقر على مساعدة > البحث عن تحديثات (أو استوديو Android > البحث عن التحديثات على نظام التشغيل macOS). وإذا لم يكن كذلك، يمكنك تنزيل أحدث إصدار ثابت.
بالإضافة إلى ذلك، إذا كنت قد استخدمت بشكل نشط وظيفة طلب سحب GitHub في بيئة التطوير المتكاملة (IDE)، ننصحك بشدة بإبطال أي رموز من رموز GitHub يتم استخدامها بواسطة المكوّن الإضافي. وبما أنّ المكوِّن الإضافي يمكنه استخدام دمج OAuth أو رموز الدخول الشخصية (PATs)، يُرجى وضع علامة في المربّع وإبطالهما حسب الضرورة:
- لإبطال الوصول إلى عملية دمج OAuth، انتقِل إلى التطبيقات > تطبيقات OAuth المعتمَدة وأبطِل الوصول إلى رمز JetBrains IDE Integration.
- لإبطال وصول PATs، انتقِل إلى رموز الدخول الشخصية واحذف الرمز المميّز الذي تم إصداره لمكوّن GitHub الإضافي. يكون اسم الرمز المميّز التلقائي هو المكوّن الإضافي للدمج IntelliJ IDEA GitHub، ولكن يُحتمَل أنّك تستخدم اسمًا مخصّصًا.
بعد إبطال الوصول إلى الرموز المميّزة، ستحتاج إلى إعداد المكوّن الإضافي مجددًا لكي تعمل من جديد جميع ميزات المكوِّن الإضافي، بما في ذلك عمليات Git.
نعتذر عن أي إزعاج ونحث جميع المستخدمين على التحديث فورًا لحماية الرموز البرمجية الخاصة بهم وبياناتهم.
يتضمّن هذا التحديث البسيط أيضًا إصلاحات الأخطاء هذه.
Android Studio Jellyfish | رمز التصحيح 1 للإصدار 2023.3.1 والإصدار 8.4.1 من AGP (أيار/مايو 2024)
يتضمّن هذا التحديث البسيط إصلاحات الأخطاء هذه.
تم تقليص صفوف المكتبة
بدءًا من الإصدار 8.4 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android"، إذا تم تصغير مشروع مكتبة Android، سيتم نشر فئات البرامج المُقلصة للنشر بين المشاريع. ويعني هذا أنّه إذا كان التطبيق يعتمد على الإصدار المصغّر من المشاريع الفرعية لمكتبة Android، ستتضمن حزمة APK فئات مكتبة Android المصغّرة. قد تحتاج إلى تعديل قواعد الاحتفاظ بالمكتبة في حال عدم توفُّر فئات في حزمة APK.
إذا كنت تنشئ وتنشر AAR، سيتم تضمين الأواني المحلية التي تعتمد عليها مكتبتك بشكل غير متقلّص في هذه الميزة، ما يعني أنّ أداة تقليل الرموز لن يتم تشغيلها عليها.
للعودة إلى السلوك السابق، يمكنك ضبط
android.disableMinifyLocalDependenciesForLibraries في ملف gradle.properties
والإبلاغ عن الخطأ.
ستؤدي الإصدارات المستقبلية من AGP إلى إزالة هذه العلامة وإزالة هذه العلامة.