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

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

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

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

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

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

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

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

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

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

اختيار قيمة `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 حول استخدام أدوات الاختبار.