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

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

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

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

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

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

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

يتم تجميع مكتبة Android في شكل ملف أرشيف Android (AAR). تتكوّن البيانات الوصفية لملف AAR من سمات تساعد IDE في استخدام المكتبات. إذا تم استخدام مكتبتك من خلال إعدادات غير متوافقة ، وتم إعداد البيانات الوصفية لـ 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 حول استخدام مواد اختبار.