يستند نظام تصميم "استوديو Android" إلى Gradle، ويضيف المكوّن الإضافي لنظام Gradle المتوافق مع Android العديد من الميزات المخصصة لتصميم تطبيقات Android. ومع أنّه يتم عادةً تحديث المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) في خطوة القفل باستخدام "استوديو Android"، يمكن تشغيل المكوّن الإضافي (وباقي نظام Gradle) بشكل مستقل عن "استوديو Android" ويتم تحديثه بشكل منفصل.
توضّح هذه الصفحة كيفية الحفاظ على تحديث أدوات Gradle باستمرار، والتعديلات التي تم إجراؤها في آخر التحديثات. للاطّلاع على ملاحظات الإصدار للإصدارات السابقة من مكوّن Gradle المتوافق مع Android، يمكنك الاطّلاع على ملاحظات الإصدار السابقة.
لمعرفة المشاكل التي تم إصلاحها في هذا الإصدار من المكوّن الإضافي لنظام Gradle المتوافق مع Android، يمكنك الاطّلاع على المشاكل التي تم إغلاقها.
للحصول على ملخّص عام حول التغييرات التي قد تؤدي إلى تعطُّل في مكوّن Android Gradle الإضافي، يمكنك الاطّلاع على خطة تطوير المكوّن الإضافي لنظام Gradle المتوافق مع Android.
للحصول على تفاصيل حول كيفية إعداد إصدارات Android باستخدام Gradle، راجِع الصفحات التالية:
- ضبط تصميمك
- مرجع DSL للمكوّن الإضافي لنظام Gradle المتوافق مع Android
- مرجع Gradle DSL
- دليل المستخدم لأداء Gradle
لمزيد من المعلومات حول نظام تصميم Gradle، راجِع دليل مستخدم Gradle.
تحديث المكوّن الإضافي لنظام Gradle المتوافق مع Android
عند تحديث "استوديو Android"، قد تظهر رسالة تطلب منك تحديث مكوّن Android Gradle تلقائيًا إلى أحدث إصدار متاح. يمكنك اختيار قبول التحديث أو تحديد إصدار يدويًا استنادًا إلى متطلبات تصميم مشروعك.
يمكنك تحديد إصدار المكوّن الإضافي إمّا في قائمة الملف > بنية المشروع > المشروع في "استوديو 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 في المرة التالية التي تُنشئ فيها مشروعك أو انقر على ملف > مزامنة المشروع مع ملفات 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 إلى 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.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"
يستند نظام تصميم "استوديو Android" إلى Gradle، ويضيف مكوّن Android Gradle الإضافي (AGP) العديد من الميزات الخاصة بتصميم تطبيقات Android. يسرد الجدول التالي إصدار AGP المطلوب لكل إصدار من إصدارات استوديو Android.
إصدار "استوديو Android" | إصدار AGP المطلوب |
---|---|
كوالا | 2024.1.1 | 3.2-8.5 |
قنديل البحر | 2023.3.1 | 3.2-8.4 |
الإغوانا | 1 تشرين الثاني (نوفمبر) 2023 | 3.2-8.3 |
القنفذ | 1.1.2023 | 3.2 إلى 8.2 |
زرافة | 1 حزيران (يونيو) 2022 | 8.1-3.2 |
طائر الفلامينغو | 1 تشرين الثاني (نوفمبر) 2022 | 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 | 7.2-3.2 |
Bumblebee | 2021.1.1 | 3.2-7.1 |
Arctic Fox | 2020.3.1 | من 3.1 إلى 7.0 |
للاطّلاع على معلومات حول الميزات الجديدة في مكوّن Android Gradle الإضافي، يمكنك الاطّلاع على ملاحظات إصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android.
الحد الأدنى لإصدارات الأدوات لمستوى واجهة برمجة تطبيقات Android
يتوفّر عدد أدنى من إصدارات "استوديو Android" وAGP المتوافقة مع مستوى معيّن من واجهة برمجة التطبيقات. قد يؤدي استخدام إصدارات أقل من "استوديو Android" أو AGP إلى ما هو مطلوب في targetSdk
أو compileSdk
لمشروعك، قد يؤدي إلى حدوث مشاكل غير متوقَّعة. نقترح استخدام أحدث إصدار لمعاينة "استوديو Android" وAGP للعمل على المشاريع التي تستهدف إصدارات المعاينة من نظام التشغيل Android. يمكنك
تثبيت
إصدارات المعاينة
من "استوديو Android" إلى جانب الإصدار الثابت.
في ما يلي الحد الأدنى لإصدارات "استوديو Android" وAGP:
مستوى واجهة برمجة التطبيقات | الحد الأدنى لإصدار "استوديو Android" | الحد الأدنى لإصدار AGP |
---|---|---|
معاينة VanillaIceCream | قنديل البحر | 2023.3.1 | 8.4 |
34 | القنفذ | 1.1.2023 | 8.1.1 |
33 | طائر الفلامينغو | 1 تشرين الثاني (نوفمبر) 2022 | 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. |
العُقدة (NDK) | لا ينطبق | 26.1.10909125 | ثبِّت أو اضبط نسخة مختلفة من NDK. |
JDK | 17 | 17 | للاطلاع على مزيد من المعلومات، راجع إعداد إصدار JDK. |
في ما يلي الميزات الجديدة في الإصدار 8.4 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.
تم تصغير صفوف المكتبة
بدءًا من الإصدار 8.4 من المكوّن الإضافي لنظام Gradle المتوافق مع Android، إذا تم تصغير مشروع مكتبة Android، سيتم نشر صفوف البرامج القصيرة لنشرها بين المشاريع. وهذا يعني أنّه إذا كان التطبيق يعتمد على الإصدار الذي تم تقليصه من المشروعات الفرعية لمكتبة Android، ستتضمّن حزمة APK صفوف مكتبة Android محدودة. وقد تحتاج إلى تعديل قواعد إبقاء المكتبة في حال عدم توفّر فئات في حزمة APK.
إذا كنت تنشئ وتنشر AAR، سيتم تضمين الأواني التي تعتمد عليها مكتبتك بدون تقليصها في AAR، ما يعني أنّ أداة تقليص الرموز لن تعمل عليها.
للعودة إلى السلوك السابق، اضبط
android.disableMinifyLocalDependenciesForLibraries
في ملف gradle.properties
وأبلغ عن الخطأ.
وستزيل الإصدارات المستقبلية من AGP هذه العلامة.