استخدام "مساعد ترقية مكوّن Google Gradle الإضافي" على Android

إنّ مساعد ترقية مكوّن Android Gradle الإضافي (AGP) هو أداة في "استوديو Android" تساعدك في ترقية إصدار AGP المُستخدَم في مشروعك.

هناك إصدارات متكررة لتغييرات AGP ذات صلة بالميزات الجديدة لضبط إصدارك، وواجهات برمجة التطبيقات الجديدة التي يمكنك استخدامها بواسطة مكونات Gradle الإضافية الأخرى، وتحسينات لدمج إصدار المشروع مع Android Studio. تتيح لك ترقية إصدار AGP المستخدم في مشروعك الاستفادة من أحدث الميزات.

للحصول على مزيد من المعلومات عن بنية المشاريع المقترَحة لمساعِد الترقية، اطّلِع على قسم الإعداد في هذه الصفحة.

حالات استخدام مساعد ترقية AGP

يرشدك مساعد ترقية AGP خلال التغييرات المطلوبة لترقية إصدارات AGP. في ما يلي حالات الاستخدام الأكثر شيوعًا لـ "مساعد الترقية":

• تغييرات في البنية: يحاول "مساعد الترقية" ترجمة ملفات الإصدار لإصدار قديم من AGP إلى الملفات المطلوبة لإصدار أحدث من AGP. ومع تطوير AGP، يتم تحديث ملفات الإصدار لتتوافق مع الواجهات عند استبدالها أو إيقافها أو عدم توافقها بمرور الوقت.

• متطلبات التوافق بين AGP و Gradle: يدرك "مساعد الترقية" متطلبات التوافق بين AGP وGrdle، ويساعد في ضمان استخدام الإصدار المطلوب من Gradle لإصدارك من AGP.

• متطلبات التوافق بين AGP ومكوّنات Gradle الإضافية التابعة لجهات خارجية: يدرك "مساعِد الترقية" متطلبات التوافق بين AGP وبعض المكوّنات الإضافية التابعة لجهات خارجية، ويساعد في ضمان أنّك تستخدم إصدارات من مكونات Gradle الإضافية التابعة لجهات خارجية المطلوبة لإصدارك من AGP.

بشكل عام، يعمل مساعِد الترقية على تسهيل عملية تعديل ملفات الإصدار وفهم رسائل الخطأ ذات الصلة بعد ترقية AGP. ويشرح "المساعد" أيضًا سبب أهمية التغييرات المُقترَحة.

كيفية استخدام مساعِد ترقية AGP

لاستخدام "مساعِد الترقية"، تأكَّد من أنّ بنية مشروعك تتلاءم مع الأداة، ثم شغِّلها من "استوديو Android" على النحو الموضّح في مقالة تشغيل مساعد الترقية.

إعداد المشروع

قبل تشغيل "مساعِد الترقية"، عليك التأكّد من تنسيق مشروعك والاحتفاظ بنسخة احتياطية منه بشكلٍ صحيح. للتأكد من إعداد مساعد ترقية AGP بشكل صحيح، اقرأ الأقسام التالية.

تنظيم مشروعك باستخدام ملفات إصدار Gradle واللغة الخاصة بالنطاق

للاستفادة إلى أقصى حدّ من مساعِد ترقية AGP، عليك إجراء ما يلي:

• ضبط الإصدار باستخدام ملفات إصدار Gradle: يعتمد "مساعِد الترقية" على التحليل الثابت لملفات إصدار Gradle. وللاستفادة إلى أقصى حد من "مساعد الترقية"، يمكنك ضبط إصدارك باستخدام ملفات الإصدار هذه.

• استخدام لغة إصدار تعريفي خاصة بنطاق: يتم التعبير عن ملفات إصدار Gradle بأسلوب Groovy أو Kotlin. ومع ذلك، كلما كان تعبير إعدادات المشروع أكثر وضوحًا، زادت احتمالية عثور "مساعد الترقية" بنجاح على جميع المواضع التي تحتاج إلى تعديل للترقية.

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

الاحتفاظ بنسخة احتياطية من مشروعك

قبل استخدام "مساعِد الترقية"، ننصحك بألا يكون لمشروعك أي تغييرات غير مُلتزمة بها، كما يظهر في نظام التحكّم في الإصدار. إذا كنت لا تستخدم التحكم في الإصدار، فاستخدم نسخة احتياطية من آخر إصدار جيد معروف في هذه المرحلة.

بعد تشغيل "مساعد الترقية" وإنشاء المشروع واختباره بنجاح، يمكنك إدراج الإصدار الجديد من المشروع في نظام التحكم في الإصدار.

تشغيل "مساعد الترقية"

لتشغيل "مساعِد الترقية"، اتّبِع الخطوات التالية:

1. لتشغيل مساعِد الترقية، انتقِل إلى الأدوات > مساعد ترقية AGP أو انقر على رسالة الإشعار التي تظهر في الشكل 1.

   تعرض نافذة الأداة التي تظهر تفاصيل الترقية التلقائية، بما في ذلك إصدار AGP الحالي وأحدث إصدار متوافق مع هذا الإصدار من "استوديو Android".

   

2. راجِع الخطوات المطلوبة والمقترَحة.

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

3. لتنفيذ عملية الترقية، اختَر الخطوات المطلوبة والمطلوبة وانقر على تنفيذ الخطوات المحدّدة.

   يغيّر "مساعِد الترقية" ملفات إصدار المشروع ويحاول مزامنة إصدار المشروع الجديد مع "استوديو Android". قد يستغرق هذا بعض الوقت إذا كان لديك العديد من الوحدات، حيث قد تحتاج إلى تنزيل إصدارات جديدة من المكونات الإضافية والمكتبات.

4. راجِع تقرير ما بعد الترقية. يصف هذا التقرير الخطوات التي تم إكمالها وما إذا كانت الترقية ناجحة أم غير ناجحة. وتتضمّن أيضًا إجراءً للتراجع عن التغييرات التي أجراها مساعد الترقية في حال كانت هناك مشاكل في إنشاء المشروع أو اختباره بعد الترقية.

5. بعد مزامنة المشروع بنجاح مع Android Studio، أنشئ المشروع وشغِّل مجموعات الاختبار للتأكّد من أنّ عملية الترقية لم تغيّر أي وظيفة.

6. بمجرد التحقق من أن مشروعك في حالة جيدة، اجعل الإصدار الجديد من مشروعك في نظام التحكم في الإصدار لديك.

تحديد الأخطاء وتصحيحها

إذا اقترح "مساعد الترقية" إجراء ترقية ولكن تعذّر إتمام عملية الترقية، قد يحدث ذلك عادةً بسبب إجراء تغييرات على ملفات الإصدار، ما يؤدي إلى تعذُّر المزامنة. اتّبِع الخطوات التالية للمساعدة في تحديد الخطأ وإصلاحه:

• أولاً، افحص الخطأ الذي أدى إلى تعذُّر المزامنة. في بعض الأحيان، يكون للخطأ سبب واضح، ويمكنك معالجته في ملفات إنشاء المشروع.

• وإذا لم تكن رسالة الخطأ واضحة، أو لم يكن سبب المشكلة واضحًا، عليك إعادة المشروع إلى حالته الأصلية لتقسيم الترقية إلى خطوات أصغر. يمكنك استعادة الحالة الأصلية من عنصر التحكم في الإصدار أو من النسخ الاحتياطية، والتأكد من أن المشروع في حالته الأصلية ومزامنته مع Android Studio.

تحقَّق من الخطأ من خلال اتّباع نوعَين من تقسيمات الترقية:

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

• يمكنك تنفيذ كل خطوة على حدة في إطار عملية الترقية. بعد تحديد عملية الترقية التي تؤدي إلى حدوث المشكلة، قد يكون بإمكانك إيقاف الخطوات الفردية ضمن الترقية. وإذا كان ذلك ممكنًا، حاوِل تنفيذ كل خطوة واحدة في كل مرة لمعرفة أي من هذه الخطوات يتسبب في حدوث الخطأ. إذا لم تتمكن من العثور على الخطوة المسؤولة عن ذلك، راجِع ملاحظات الإصدار لأي مكونات إضافية أخرى من Gradle تستخدمها لمعالجة مشاكل التوافق مع Gradle أو AGP. في بعض الأحيان، يعالج الإصدار الجديد استخدام واجهات برمجة التطبيقات المتوقّفة أو الداخلية.

• الإبلاغ عن خطأ: أحيانًا تنجح جميع الخطوات التحضيرية والمزامنة ولكن خطوة الترقية النهائية ما زالت تفشل. في هذه الحالة، يُرجى الإبلاغ عن خطأ. حتى إذا نجحت في إصلاح الخطأ بنفسك، يمكنك إبلاغ أداة تتبع الأخطاء بالخطأ الأصلي، حتى يمكن لفريق التطوير حل المشكلة.