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

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

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

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

بدءًا من الإصدار 7.0 من "مكوّن Android الإضافي لبرنامج Gradle"، يمكنك ضبط مساحة الاسم في ملف 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 أقل من المطلوب من خلال تبعية المكتبة، إذا لم تكن المكتبة ضرورية لوظيفة التطبيق الأساسية، وذلك عن طريق إجراء عمليات التحقّق من وقت التشغيل قبل استدعاء المكتبة. لذلك، اضبط الحد الأدنى لإصدار حزمة تطوير البرامج (SDK) لمكتبتكminSdkVersion على قيمة منخفضة بما يكفي ليتم تضمينها في التطبيقات واستدعاؤها عندما يكون ذلك ممكنًا، للمساعدة في الوصول إلى المزيد من المستخدمين.

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

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

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

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

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

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

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

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

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

اختيار قيمة 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، يمكن لـ AGP إنشاء تجهيزات اختبار لمشاريع المكتبات بالإضافة إلى مشاريع التطبيقات والميزات الديناميكية.

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

أنيق

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

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

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