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

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

اختيار مساحة اسم

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

بدءًا من الإصدار 7.0 من "مكوّن Android الإضافي لبرنامج Gradle"، يمكنك ضبط مساحة الاسم في ملف build.gradle الخاص بالتطبيق، كما هو موضّح في مثال الرمز البرمجي التالي:

Groovy

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 في عمليات الفحص. للحصول على مزيد من المراجع حول استخدام التعليقات التوضيحية لتحسين رموز واجهة برمجة التطبيقات وواجهات برمجة التطبيقات، راجِع تحسين فحص الرموز باستخدام التعليقات التوضيحية.

إعداد البيانات الوصفية الخاصة بـ AAR

يتم تجميع مكتبة Android في شكل ملف Android Archive (AAR). تتكوّن البيانات الوصفية لملف AAR من خصائص تساعد مكوّن AGP في استخدام المكتبات. إذا كانت مكتبتك مستخدَمة من خلال إعداد غير متوافق وتم إعداد بيانات وصفية لملف AAR، ستظهر للمستخدمين رسالة خطأ لمساعدتهم في حل المشكلة.

اختَر قيمة minCompileSdk

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

يمكن ضبط القيمة minCompileSdk في الحِزم defaultConfig{} وproductFlavors{} وbuildTypes{} في ملف build.gradle على مستوى الوحدة:

Groovy

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، يمكن لمكوّن Android الإضافي لنظام Gradle إنشاء أدوات اختبار لمشاريع المكتبات، بالإضافة إلى مشاريع التطبيقات والميزات الديناميكية.

عند نشر مكتبة ليستخدمها الآخرون، ننصحك بإنشاء بيانات اختبار ثابتة لواجهة برمجة التطبيقات. يمكن تفعيل بيانات الاختبار في ملف build.gradle على مستوى الوحدة:

Groovy

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

عند تفعيل بيانات الاختبار الثابتة، ينشئ Gradle تلقائيًا مجموعة مصادر src/testFixtures يمكنك كتابة بيانات الاختبار الثابتة فيها.

لمزيد من المعلومات، راجِع مستندات Gradle حول استخدام بيانات الاختبار الثابتة.