يستند نظام تصميم "استوديو 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.3.0 من
ملف build.gradle.kts
:
Kotlin
plugins { id("com.android.application") version "8.3.0" apply false id("com.android.library") version "8.3.0" apply false id("org.jetbrains.kotlin.android") version "1.9.23" apply false }
رائع
plugins { id 'com.android.application' version '8.3.0' apply false id 'com.android.library' version '8.3.0' apply false id 'org.jetbrains.kotlin.android' version '1.9.23' apply false }
تنبيه: يجب عدم استخدام التبعيات الديناميكية في أرقام
الإصدارات، مثل
'com.android.tools.build:gradle:8.3.+'
.
قد يؤدي استخدام هذه الميزة إلى إجراء تحديثات غير متوقّعة في الإصدار وإلى صعوبة
حلّ الاختلافات في الإصدارات.
إذا لم يتم تنزيل إصدار المكوّن الإضافي المحدَّد، ينزِّله Gradle في المرة التالية التي تُنشئ فيها مشروعك أو انقر على ملف > مزامنة المشروع مع ملفات Gradle من شريط قوائم "استوديو Android".
تعديل Gradle
عند تحديث "استوديو Android"، قد تظهر لك رسالة تطلب منك أيضًا تحديث Gradle إلى أحدث إصدار متاح. يمكنك اختيار قبول التحديث أو تحديد إصدار يدويًا استنادًا إلى متطلبات تصميم مشروعك.
يسرد الجدول التالي إصدار Gradle المطلوب لكل إصدار من المكوِّن الإضافي لنظام Gradle المتوافق مع Android. للحصول على أفضل أداء، يجب استخدام أحدث إصدار ممكن من كل من Gradle والمكون الإضافي.
إصدار المكوِّن الإضافي | الحد الأدنى المطلوب لإصدار Gradle |
---|---|
8.4 (إصدار أولي) | نموذج 8.6-rc-1 |
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.3 باستخدام Gradle Wrapper.
ملاحظة: تحتاج إلى تشغيل هذا الأمر مرتين لترقية كل من Gradle
و"Gradle Wrapper" (التفاف النص) نفسه (لمزيد من المعلومات، يُرجى مراجعة
ترقية Gradle Wrapper).
gradle wrapper --gradle-version 8.3
وقد يتعذّر ذلك في بعض الحالات، مثلاً إذا كنت قد عدّلت AGP للتو ولم يعُد متوافقًا مع إصدار Gradle الحالي. وفي هذه الحالة،
عليك تعديل مرجع توزيع Gradle في
ملف gradle/wrapper/gradle-wrapper.properties
. في المثال التالي، يتم ضبط إصدار Gradle على 8.3 في ملف gradle-wrapper.properties
.
...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.3-bin.zip
...
المكوّن الإضافي لنظام Gradle المتوافق مع Android والتوافق مع "استوديو Android"
يستند نظام تصميم "استوديو Android" إلى Gradle، ويضيف مكوّن Android Gradle الإضافي (AGP) العديد من الميزات الخاصة بتصميم تطبيقات Android. يسرد الجدول التالي إصدار AGP المطلوب لكل إصدار من إصدارات استوديو Android.
إصدار "استوديو Android" | إصدار AGP المطلوب |
---|---|
قنديل البحر | 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 |
Electric eel | 2022.1.1 | 3.2-7.4 |
إصدارات سابقة
إصدار "استوديو Android" | إصدار AGP المطلوب |
---|---|
دولفين | 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.4 | 8.4 | لمزيد من المعلومات، يمكنك الاطّلاع على تحديث Gradle. |
أدوات إنشاء حِزم تطوير البرامج (SDK) | 34.0.0 | 34.0.0 | ثبِّت أو ضبط أدوات إصدار SDK. |
العُقدة (NDK) | لا ينطبق | 25.1.8937393 | ثبِّت أو اضبط نسخة مختلفة من NDK. |
JDK | 17 | 17 | للاطلاع على مزيد من المعلومات، راجع إعداد إصدار JDK. |
في ما يلي الميزات الجديدة في الإصدار 8.3 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.
إصدارات التصحيح
في ما يلي قائمة بإصدارات التصحيح في الإصدار Android Studio Iguana والإصدار 8.3 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.
Android Studio Iguana | 2023.2.1 التصحيح 1 وAGP 8.3.1 (آذار/مارس 2024)
يتضمّن هذا التحديث الثانوي هذه إصلاحات الأخطاء.
دعم كتالوجات إصدارات Gradle
يتوافق "استوديو Android" مع ميزة Gradle Version Catalogs المستندة إلى لغة TOML، وهي ميزة تتيح لك إدارة التبعيات في موقع مركزي واحد ومشاركة التبعيات في الوحدات أو المشاريع. يساعد "استوديو Android" الآن في تسهيل عملية ضبط كتالوجات الإصدارات من خلال اقتراحات المحرّرين والدمج مع مربّع حوار بنية المشروع. تعرَّف على كيفية إعداد ميزة Gradle Version Catalogs وضبطها أو كيفية نقل إصدارك إلى كتالوجات الإصدارات.
إكمال الرمز والتنقل
يتيح "استوديو Android" إمكانية إكمال الرمز عند تعديل كتالوج الإصدار بتنسيق ملف TOML أو إضافة تبعية من كتالوج الإصدار إلى ملف إصدار. لاستخدام إكمال الرمز، اضغط على Ctrl+Space
(Command+Space على نظام التشغيل macOS). بالإضافة إلى ذلك، يمكنك الانتقال بسرعة من مرجع التبعية في ملف build.gradle
في تطبيقك إلى المكان الذي تم تعريفه به في كتالوج الإصدارات بالضغط على Ctrl+b
(Command+b على نظام التشغيل macOS).
الدمج مع مربّع حوار "بنية المشروع"
إذا كان مشروعك يستخدم كتالوج إصدارات محدّد بتنسيق ملف TOML، يمكنك تعديل المتغيرات التي حدّدتها من خلال مربّع الحوار بنية المشروع في قسم عرض المتغيّرات (ملف > بنية المشروع > المتغيرات) في Android Studio. لكل كتالوج إصدار، توجد قائمة منسدلة تسرد المتغيرات من هذا الكتالوج. لتعديل متغيّر، انقر على قيمته واستبدله. عند حفظ هذه التغييرات، يتم تحديث ملف TOML وفقًا لذلك.
يمكنك أيضًا تعديل التبعيات في عرض مربع الحوار بنية المشروع التبعيات (ملف > بنية المشروع > التبعيات). لتحديث الإصدارات باستخدام مربع الحوار بنية المشروع، انتقِل إلى الوحدة والتبعية التي تريد تعديلها، ثم حدِّث حقل الإصدار المطلوب. وعند حفظ هذه التغييرات، يتم تعديل ملف TOML وفقًا لذلك. لاحظ أنه إذا تم تحديد إصدار التبعية باستخدام متغير، فإن تحديث الإصدار بهذه الطريقة يؤدي مباشرةً إلى استبدال المتغير بقيمة غير قابلة للتغيير. وتجدر الإشارة أيضًا إلى أن إزالة التبعية من ملف الإصدار، سواء كنت تستخدم مربع الحوار بنية المشروع أم لا، لا يؤدي إلى إزالة التبعية من كتالوج الإصدارات.
القيود والمشاكل المعروفة
في ما يلي المشاكل أو القيود المعروفة المتعلّقة بتوافق كتالوجات إصدار Gradle في "استوديو Android":
حدث خطأ أثناء تمييز إعلانات الأسماء المستعارة للمكوّنات الإضافية في ملفات نصوص Kotlin البرمجية: عند إضافة تعريف مكوّن إضافي للنموذج
alias(libs.plugins.example)
، يضيف المحرِّر خطًا أحمر تحت الجزءlibs
. هذه مشكلة معروفة في الإصدارات 8.0 من Gradle والإصدارات الأقدم، وسيتم حلّها في إصدار مستقبلي من Gradle.لا يتوافق "استوديو Android" إلا مع كتالوجات الإصدارات بتنسيق TOML: في الوقت الحالي، لا يتوفّر دعم "إكمال الرمز البرمجي لـ "استوديو Android" والتنقل و"بنية المشروع" إلا لكتالوجات الإصدارات المحدّدة بتنسيق ملف TOML. مع ذلك، سيظل بإمكانك إضافة كتالوج الإصدارات مباشرةً في ملف
settings.gradle
واستخدام العناصر الاعتمادية الخاصة به في مشروعك.التنقل في ملفات إصدار KTS غير متاح: الانتقال إلى تعريف التبعية في كتالوج الإصدار باستخدام Control+النقر (Command+النقر على نظام التشغيل macOS) غير متاح حتى الآن لملفات الإصدار المكتوبة باستخدام نص Kotlin البرمجي.
يضيف "مساعد Firebase" التبعيات مباشرةً في النصوص البرمجية للإصدارات: يضيف مساعد Firebase التبعيات مباشرةً إلى النصوص البرمجية للإصدار، بدلاً من كتالوجات الإصدارات.
وظيفة "البحث عن الاستخدامات" غير متاحة: لا تتوفر بعد إمكانية العثور على الاستخدامات لمتغير كتالوج الإصدار في ملفات الإصدار الأخرى، سواء كان ملف الإصدار بتنسيق KTS أو Groovy. وهذا يعني أنّ استخدام Control+النقر (Command+النقر على نظام التشغيل macOS) على تعريف متغيّر في كتالوج الإصدارات لا يؤدي إلى ملفات الإصدار التي يُستخدَم فيها المتغيّر.
يعرض مربّع حوار "بنية المشروع" في "استوديو Android" عدة ملفات كتالوج إذا كانت في مجلد
gradle
الجذر، ولكنها لا تعرض كتالوجات لإصدار مركب. على سبيل المثال، إذا كان لديك ملفا كتالوج - أحدهما لتطبيقك والآخر لإصدار مركب - فإن مربع حوار "بنية المشروع" يعرض ملف كتالوج التطبيق فقط. يمكنك استخدام تصميم مركب، ولكن عليك تعديل ملف TOML مباشرةً.
إحصاءات إضافية عن حِزم SDK: المشاكل المتعلّقة بالسياسات
يعرض "استوديو Android" تحذيرات من الوبر في ملفَي build.gradle.kts
وbuild.gradle
، وفي مربع حوار بنية المشروع لحِزم تطوير البرامج (SDK) المتاحة للجميع التي تنتهك سياسات Play في أداة Google Play SDK Index. ويجب تعديل أي تبعيات تنتهك سياسات Play لأنّ هذه الانتهاكات قد تمنعك من النشر على Google Play Console في المستقبل. وتُكمِّل التحذيرات بشأن انتهاك السياسة
تحذيرات بشأن الإصدارات القديمة
التي يعرضها "استوديو Android".
إتاحة إصدار Compesdk من استوديو Android
يعرض "استوديو Android" تحذيرًا إذا كان مشروعك يستخدم compileSdk
غير متوافق مع الإصدار الحالي من "استوديو Android". وتقترح الأداة أيضًا الانتقال إلى إصدار من "استوديو Android" يتوافق مع compileSdk
الذي يستخدمه مشروعك. يُرجى العلم أنّ
ترقية "استوديو Android" قد تتطلّب أيضًا ترقية AGP.
يعرض AGP أيضًا تحذيرًا في نافذة أداة إنشاء إذا كان الإصدار الحالي من AGP غير متوافق مع compileSdk
الذي يستخدمه مشروعك.
تغييرات في سلوك الوبر
بدءًا من الإصدار 8.3.0-alpha02 من المكوّن الإضافي لنظام Gradle المتوافق مع Android، عند تشغيل أداة Lint على إحدى الوحدات، يتم تنفيذ مهام تحليل الوبر المنفصلة للمكوّنات الرئيسية ومكوّنات الاختبار للوحدة. السبب في هذا التغيير هو تحسين الأداء.
للعودة إلى السلوك السابق، يجب ضبط
android.experimental.lint.analysisPerComponent=false
في
ملف gradle.properties
.
تصغير الموارد بدقة وبشكل تلقائي
يتم تلقائيًا تفعيل ميزة "التصغير الدقيق للموارد" التي تزيل الإدخالات غير المستخدَمة من ملف resources.arsc
وتزيل ملفات الموارد غير المستخدَمة.
عند تفعيل عملية التقليص هذه، يتم تقليل جدول الموارد ولا يتم تضمين سوى إدخالات مجلد res
المشار إليها في حزمة APK.
لإيقاف التصغير الدقيق للموارد، اضبط
android.enableNewResourceShrinker.preciseShrinking
على false
في
ملف gradle.properties
الخاص بالمشروع.