إعداد المكتبة للنشر

توضّح هذه الصفحة الخصائص والخيارات اللازمة لإعداد مشروع مكتبة 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 الأولوية للمواقع الجغرافية للإعدادات على النحو التالي أثناء عملية التصميم:

  1. buildTypes{}

  2. productFlavors{}

  3. 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 حول استخدام تركيبات الاختبار.