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

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

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

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

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

أنيق

android {
  namespace = 'com.example.library'
}

Kotlin

android {
  namespace = "com.example.library"
}

مساحة الاسم هي سمة من سمات المكتبة موجّهة للمطوّرين. ولا يرتبط هذا الاسم بهوية التطبيق التي يتم ضبطها باستخدام السمة applicationId.

في الإصدارات السابقة من AGP، كان من الممكن ضبط كل من السمة applicationId (للتطبيق) والسمة namespace (للمكتبة) باستخدام السمة package في ملف البيان، ما أدى إلى حدوث التباس.

ملاحظة: لا يتضمّن مشروع المكتبة applicationId، لأنّ هذه السمة خاصة بالتطبيقات فقط.

اختيار قيمة minSdkVersion

يُعدّ اختيار minSdkVersion لمكتبتك جانبًا مهمًا من جوانب نشر مكتبتك. يجب أن يعكس minSdkVersion الحد الأدنى لإصدار Android الذي يمكن أن يتوافق معه الرمز البرمجي.

يُرجى الانتباه إلى الاعتبارات التالية عند اختيار minSdkVersion:

• يؤدي اختيار قيمة منخفضة لسمة minSdkVersion بشكل عام إلى توزيع مكتبتك على نطاق أوسع.

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

• قد يؤدي اختيار قيمة عالية لـ minSdkVersion إلى منع التطبيقات من تضمين المكتبة.

  تتولى أداة دمج ملفات البيان، وهي خطوة في AGP تدمج ملفات البيان من التطبيق ومن تبعياته، فرض عدم وجود تبعيات لها قيمة minSdkVersion أعلى من التطبيق.

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

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

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

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

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

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

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

ملاحظة: لا تحتوي البيانات الوصفية لملفات AAR على سمات مهمة في وقت التشغيل، وبالتالي لا تظهر عادةً في تطبيقات Android التي تم تجميعها.

اختيار قيمة minCompileSdk

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

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

أنيق

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

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

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