توضّح هذه الصفحة الخصائص والخيارات اللازمة لإعداد مشروع مكتبة Android للنشر باستخدام المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP). حتى إذا قمت بتعيين بعض هذه الخصائص في بداية إنشاء مكتبتك، قم بمراجعة الإرشادات التالية لتحسين الإعدادات الخاصة بك.
اختيار مساحة اسم
تحتاج مكتبات Android إلى تحديد مساحة اسم لتتمكّن من إنشاء فئة R
فريدة عند تجميع الموارد. يجب أن تتطابق مساحة الاسم هذه إلى حدّ كبير مع حزمة فئة الجذر في المكتبة لتجنُّب حدوث أي التباس عند استيراد المستخدمين لصفوف عادية من المكتبة وفئة R
الخاصة بها.
بدءًا من الإصدار 7.0 من AGP، يمكنك ضبط
namespace
في ملف build.gradle
الخاص بالتطبيق، كما هو موضَّح في مثال الرمز البرمجي التالي:
رائع
android { namespace = 'com.example.library' }
Kotlin
android { namespace = "com.example.library" }
مساحة الاسم هي خاصية موجّهة للمطوّرين في المكتبة. ولا يرتبط بهوية التطبيق، التي يتم إعدادها باستخدام السمة applicationId
.
في الإصدارات السابقة من AGP، كان يمكن ضبط السمة applicationId
(لتطبيق) والسمة namespace
(للمكتبة) باستخدام سمة package
، ما أدى إلى حدوث التباس.
اختيار قيمة minSdkVersion
يعد اختيار minSdkVersion
لمكتبتك جانبًا
مهمًا في نشر مكتبتك. يجب أن يعكس minSdkVersion
الإصدار الأدنى من نظام Android الذي يمكن أن يتوافق رمزك معه.
يُرجى الانتباه إلى الاعتبارات التالية عند اختيار minSdkVersion
:
يتيح اختيار قيمة
minSdkVersion
منخفضة بشكل عام توزيع مكتبتك على نطاق أوسع.لا يتم تنفيذ التعليمات البرمجية للمكتبة بشكل عام ما لم يستدعيها التطبيق بشكل صريح. سيظل بإمكان التطبيق تشغيل التطبيق على إصدار Android أقل من الذي تقتضيه تبعية المكتبة، إذا لم تكن المكتبة ضرورية لوظائف التطبيق الأساسية، وذلك عن طريق إجراء عمليات فحص في وقت التشغيل قبل طلب المكتبة. لهذا السبب، يجب ضبط
minSdkVersion
في مكتبتك على مستوى منخفض بما يكفي لتضمينه في التطبيقات وطلبه عند الإمكان للمساعدة في الوصول إلى المزيد من المستخدمين.قد يؤدي اختيار درجة عالية من
minSdkVersion
إلى منع التطبيقات من تضمين المكتبة.إنّ دمج البيان، وهو خطوة في AGP تدمج ملفات البيان من التطبيق ومن تبعياته، يفرض عدم احتواء التبعيات على
minSdkVersion
أعلى من التطبيق.قد يؤدي اختيار مستوى عالٍ من
minSdkVersion
إلى الطلب من مطوّري التطبيقات إيقاف عمليات التحقّق من الأمان للاندماج، ما يؤدي إلى حدوث مشاكل لاحقًا في عملية التصميم.بما أنّ دمج البيان يمنع مشاريع التطبيق من تضمين المكتبات التي تحتوي على
minSdkVersion
أعلى من التطبيق نفسه، قد يوقف مطوّرو التطبيقات عمليات التحقّق من الأمان لدمج البيان لتقليل أخطاء الإصدار. ومع ذلك، قد يؤدي ذلك إلى حدوث مشاكل عدم توافق حقيقية خلال عملية النقل.قد يكون من الضروري اختيار مستوى
minSdkVersion
عالي في الحالات الخاصة التي يشمل فيها بيان المكتبة جهاز استقبال بث أو آلية أخرى يتم من خلالها تشغيل الرمز تلقائيًا.في هذه الحالات، يضمن اختيار قيمة مرتفعة من حيث
minSdkVersion
تشغيل الرمز. بدلاً من ذلك، يمكنك إيقاف السلوك التلقائي كي يتمكّن التطبيق من تفعيل تنفيذ المكتبة بعد إجراء عمليات التحقّق الصحيحة.
للسماح بالتضمين في التطبيقات، استخدِم التعليق التوضيحي RequiresApi
في مكتبتك لإعلام المتصلين بأنّ عليهم إجراء عمليات تحقُّق وقت التشغيل. يستخدم Android Lint معلومات RequiresApi
لإجراء عمليات الفحص. للاطلاع على مزيد من الموارد حول استخدام التعليقات التوضيحية لتحسين رمز واجهة برمجة التطبيقات وواجهات برمجة التطبيقات، يمكنك الاطّلاع على تحسين فحص الرموز باستخدام التعليقات التوضيحية.
إعداد البيانات الوصفية لميزة "الاقتراحات المطبّقة تلقائيًا"
يتم تجميع مكتبة Android في شكل ملف أرشيف Android (AAR). تتكون بيانات التعريف AAR من خصائص تساعد في استهلاك المكتبات AGP. إذا تم استهلاك مكتبتك من خلال عملية ضبط غير متوافقة، وتم إعداد البيانات الوصفية للاقتراحات المطبّقة تلقائيًا، ستظهر للمستخدمين رسالة خطأ لمساعدتهم في حلّ المشكلة.
اختيار قيمة minCompileSdk
بدءًا من الإصدار 4.1، يتوافق نظام AGP مع
minCompileSdk
.
يشير هذا إلى الحدّ الأدنى من
compileSdk
الذي يمكن استخدامه للمشروعات. إذا كانت مكتبتك تحتوي على إدخالات بيان أو موارد تستفيد من سمات أحدث للنظام الأساسي، عليك ضبط هذه القيمة.
يمكن ضبط القيمة minCompileSdk
في الكتل defaultConfig{}
وproductFlavors{}
وbuildTypes{}
في ملف build.gradle
على مستوى الوحدة:
رائع
android { defaultConfig { aarMetadata { minCompileSdk = 29 } } productFlavors { foo { ... aarMetadata { minCompileSdk = 30 } } } }
Kotlin
android { defaultConfig { aarMetadata { minCompileSdk = 29 } } productFlavors { register("foo") { ... aarMetadata { minCompileSdk = 30 } } } }
في حال ضبط minCompileSdk
في أماكن متعدّدة، تعطي Gradle الأولوية للمواقع الجغرافية للإعدادات على النحو التالي أثناء عملية التصميم:
buildTypes{}
productFlavors{}
defaultConfig{}
في المثال السابق، حيث يتم تحديد minCompileSdk
في كل من defaultConfig{}
وproductFlavors{}
، تكون الأولوية productFlavors{}
ويتم ضبط minCompileSdk
على 30.
لمعرفة المزيد من المعلومات حول كيفية تحديد Gradle الأولوية للإعدادات عند الجمع بين الرموز والموارد، يمكنك الاطّلاع على الإنشاء باستخدام مجموعات المصادر.
تفعيل إعدادات الاختبار
يشيع استخدام تركيبات الاختبار لإعداد التعليمات البرمجية التي يتم اختبارها أو لتسهيل اختبار أحد المكوّنات. بدءًا من الإصدار 7.1، يمكن لـ AGP إنشاء تركيبات اختبار لمشروعات المكتبة بالإضافة إلى مشروعات التطبيقات والميزات الديناميكية.
عند نشر مكتبة ليشاهدها الآخرون، فكّر في إنشاء أدوات اختبار لواجهة برمجة التطبيقات الخاصة بك. يمكن تفعيل تركيبات الاختبار في ملف build.gradle
على مستوى الوحدة:
رائع
android { testFixtures { enable = true } }
Kotlin
android { testFixtures { enable = true } }
عند تفعيل تركيبات الاختبار، ينشئ Gradle تلقائيًا
مجموعة مصادر src/testFixtures
يمكنك من خلالها كتابة تركيبات الاختبار.
لمزيد من المعلومات، راجع وثائق Gradle حول استخدام تركيبات الاختبار.