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

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

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

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

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

يرشدك "مساعِد ترقية Android Gradle Plugin" خلال التغييرات اللازمة لترقية إصدارات Android Gradle Plugin. في ما يلي حالات الاستخدام الأكثر شيوعًا لأداة Upgrade Assistant:

• تغييرات في بنية الجملة: تحاول "أداة الترقية" ترجمة ملفات الإصدار إلى ملفات متوافقة مع إصدار أحدث من "مكوّن Android الإضافي في Gradle". أثناء تطوير "مكوّن Android Gradle الإضافي"، يتم تعديل ملفات الإنشاء لتتوافق مع الواجهات عند استبدالها أو إيقافها نهائيًا أو عدم توفّرها بمرور الوقت.

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

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

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

كيفية استخدام "أداة ترقية حزمة Android Gradle"

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

إعداد مشروعك

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

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

لتحقيق أقصى استفادة من "مساعِد ترقية Android Gradle"، اتّبِع الخطوات التالية:

• ضبط الإصدار باستخدام ملفات تصميم Gradle: يعتمد "مساعد الترقية" على التحليل الثابت لملفات تصميم Gradle. للاستفادة إلى أقصى حدّ من أداة Upgrade Assistant، اضبط إصدارك باستخدام ملفات الإصدار هذه. استخدِم كتالوجات إصدارات Gradle للإشارة إلى التبعيات والمكوّنات الإضافية المحدّدة في ملف libs.versions.toml ضمن الدليل الفرعي gradle في مشروعك.

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

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

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

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

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

تشغيل "أداة الترقية"

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

1. لتشغيل "أداة الترقية"، انتقِل إلى الأدوات > أداة ترقية AGP أو انقر على طلب الإشعار، كما هو موضّح في الشكل 1.

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

   

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

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

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

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

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

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

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

تحديد المشاكل وحلّها

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

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

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

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

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

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

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