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

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

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

يجب أن تحدِّد مكتبات Android مساحة اسم حتى تتمكّن من إنشاء فئة R فريدة عند تجميع مواردها. يجب أن تتطابق مساحة الاسم هذه بشكل وثيق مع حزمة الفئة الجذر للمكتبة لتجنُّب حدوث التباس عندما يستورد المستخدمون klassen عادية من المكتبة وفئة 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 حول استخدام مواد اختبار.