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

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

    تفرض عملية دمج ملفات البيان، وهي إحدى خطوات "مكوّن Android الإضافي لنظام Gradle"، والتي تدمج ملفات البيان من التطبيق ومن العناصر التابعة له، ألا يكون لأي عناصر تابعة قيمة minSdkVersion أعلى من قيمة التطبيق.

  • قد يؤدي اختيار قيمة minSdkVersion عالية إلى مطالبة مطوّري التطبيقات بإيقاف عمليات التحقّق من أمان دمج ملف البيان، ما يتسبّب في حدوث مشاكل لاحقًا في عملية الإنشاء.

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

  • قد يكون من الضروري اختيار قيمة minSdkVersion عالية في حالات خاصة يتضمّن فيها بيان المكتبة أداة استقبال بث أو آلية أخرى يتم من خلالها تشغيل الرمز تلقائيًا.

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

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

إعداد البيانات الوصفية الخاصة بـ "الاقتراحات المطبّقة تلقائيًا"

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

اختيار قيمة minCompileSdk

بدءًا من الإصدار 4.1، يتيح AGP استخدام 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، يمكن لمكوّن AGP إنشاء بيانات اختبار ثابتة لمشاريع المكتبات، بالإضافة إلى مشاريع التطبيقات ومشاريع الميزات الديناميكية.

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

Groovy

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

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

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