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

توضِّح هذه الصفحة السمات والخيارات اللازمة لإعداد مشروع مكتبة 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 حول استخدام مواد اختبار.