إنشاء مكتبة Android

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

ومع ذلك، بدلاً من تجميعها في حزمة APK تعمل على جهاز، يتم تجميع مكتبة Android في ملف Android Archive (AAR) يمكنك استخدامه كعنصر تابع لوحدة تطبيق Android. على عكس ملفات JAR، توفّر ملفات AAR الوظائف التالية لتطبيقات Android:

• يمكن أن تحتوي ملفات AAR على موارد Android وملف بيان يتيح لك تجميع الموارد المشتركة، مثل التصاميم والرسومات، بالإضافة إلى فئات وأساليب Kotlin أو Java.
• يمكن أن تحتوي ملفات AAR على مكتبات C/C++‎ لاستخدامها في رمز C/C++‎ الخاص بوحدة التطبيق.

يكون استخدام وحدة المكتبة مفيدًا في الحالات التالية:

• عند إنشاء تطبيقات متعدّدة تستخدم بعض المكوّنات نفسها، مثل الأنشطة أو الخدمات أو تنسيقات واجهة المستخدم
• عند إنشاء تطبيق يتضمّن عدة أشكال مختلفة من حِزم APK، مثل إصدار مجاني وإصدار مدفوع، وتتشارك هذه الأشكال في المكوّنات الأساسية

في كلتا الحالتين، انقل الملفات التي تريد إعادة استخدامها إلى وحدة مكتبة، ثم أضِف المكتبة كملحَق لكل وحدة تطبيق.

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

إنشاء وحدة مكتبة

لإنشاء وحدة مكتبة جديدة في مشروعك، اتّبِع الخطوات التالية:

1. انقر على ملف > جديد > وحدة جديدة.
2. في مربّع الحوار إنشاء وحدة جديدة الذي يظهر، انقر على مكتبة Android، ثم انقر على التالي.

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

3. أدخِل اسمًا للمكتبة واختَر الحد الأدنى لإصدار حزمة تطوير البرامج (SDK) للرمز البرمجي في المكتبة، ثم انقر على إنهاء.

بعد اكتمال مزامنة مشروع Gradle، يظهر نموذج المكتبة في نافذة المشروع. إذا لم يظهر لك مجلد الوحدة النمطية الجديدة، تأكَّد من أنّ اللوحة تعرض طريقة العرض Android.

تحويل وحدة تطبيق إلى وحدة مكتبة

إذا كان لديك وحدة تطبيق حالية تتضمّن رمزًا برمجيًا تريد إعادة استخدامه، يمكنك تحويلها إلى وحدة مكتبة باتّباع الخطوات التالية:

1. افتح ملف build.gradle على مستوى الوحدة، إذا كنت تستخدم Groovy، أو ملف build.gradle.kts، إذا كنت تستخدم نص Kotlin البرمجي.
2. احذف السطر الخاص بـ applicationId. يمكن لوحدة تطبيق Android فقط تحديد ذلك.
3. ابحث عن كتلة `plugins` في أعلى الملف التي تبدو على النحو التالي:

   Groovy

     plugins {
         id 'com.android.application'
     }
     

   Kotlin

     plugins {
         id("com.android.application")
     }
     

   غيِّرها إلى ما يلي:

   Groovy

     plugins {
         id 'com.android.library'
     }
     

   Kotlin

     plugins {
         id("com.android.library")
     }
     

4. احفظ الملف وانقر على ملف > مزامنة المشروع مع ملفات Gradle.

يظل هيكل الوحدة النمطية كما هو، ولكنها تعمل الآن كمكتبة Android. ينشئ الإصدار ملف AAR بدلاً من ملف APK.

عندما تريد إنشاء ملف AAR، اختَر وحدة المكتبة في نافذة المشروع وانقر على إنشاء > إنشاء حزمة APK.

إضافة التبعيات باستخدام مربّع الحوار "بنية المشروع"

يمكنك استخدام مربّع الحوار بنية المشروع لإضافة التبعيات إلى مشروعك. توضّح الأقسام التالية كيفية استخدام مربّع الحوار لإضافة التبعيات.

استخدام مكتبتك من داخل المشروع نفسه

لاستخدام رمز مكتبة Android الجديدة في تطبيق آخر أو وحدة مكتبة ضمن المشروع نفسه، أضِف عنصرًا تابعًا على مستوى المشروع:

1. انتقِل إلى ملف > بنية المشروع > التبعيات.
2. اختَر الوحدة التي تريد إضافة المكتبة إليها.
3. في علامة التبويب التبعيات المعلَنة، انقر على واختَر تبعية الوحدة من القائمة.
   
   

4. في مربّع الحوار إضافة تبعية الوحدة، اختَر وحدة المكتبة.

   

5. اختَر الإعداد الذي يتطلّب هذه التبعية أو اختَر التنفيذ إذا كان ينطبق على جميع الإعدادات، ثم انقر على حسنًا.

يعدّل Android Studio ملف build.gradle أو build.gradle.kts الخاص بالوحدة لإضافة التبعية، وذلك بالشكل التالي:

  implementation project(path: ":example-library")

  implementation(project(":example-library"))

استخدام مكتبتك في مشاريع أخرى

الطريقة المقترَحة لمشاركة التبعيات (ملفات JAR وAAR) هي استخدام مستودع Maven، سواء كان مستضافًا على خدمة مثل Maven Central أو باستخدام بنية دليل على القرص المحلي. لمزيد من المعلومات حول استخدام مستودعات Maven، راجِع المستودعات البعيدة.

عند نشر مكتبة Android في مستودع Maven، يتم تضمين البيانات الوصفية حتى يتم تضمين الموارد التابعة للمكتبة في الإصدار الذي يستخدمها. يتيح ذلك إزالة التكرار تلقائيًا من المكتبة إذا تم استخدامها في أماكن متعددة.

لاستخدام رمز مكتبة Android في وحدة تطبيق أخرى في مشروع مختلف، اتّبِع الخطوات التالية:

1. انتقِل إلى ملف > بنية المشروع > التبعيات.
2. في علامة التبويب التبعيات المعلَن عنها، انقر على واختَر تبعيات المكتبة في القائمة.
   
   

3. في مربّع الحوار إضافة تبعية المكتبة، استخدِم مربّع البحث للعثور على المكتبة التي تريد إضافتها. يبحث هذا النموذج في المستودعات المحدّدة في الكتلة dependencyResolutionManagement { repositories {...}} في الملف settings.gradle أو settings.gradle.kts.

   

4. اختَر الإعداد الذي يتطلّب هذه التبعية أو اختَر التنفيذ إذا كان ينطبق على جميع الإعدادات، ثم انقر على حسنًا.

راجِع ملف build.gradle أو build.gradle.kts في تطبيقك للتأكّد من ظهور بيان مشابه لما يلي (استنادًا إلى إعدادات الإصدار التي اخترتها):

  implementation 'com.example:examplelibrary:1.0.0'

  implementation("com.example:examplelibrary:1.0.0")

إضافة ملف AAR أو JAR كعنصر تابع

لاستخدام رمز مكتبة Android في وحدة تطبيق أخرى، اتّبِع الخطوات التالية:

1. انتقِل إلى ملف > بنية المشروع > التبعيات.
2. في علامة التبويب التبعيات المعلَن عنها، انقر على واختَر Jar Dependency في القائمة.
   
   

3. في مربّع الحوار إضافة تبعية Jar/Aar، أدخِل مسار ملف AAR أو JAR، ثم اختَر عملية الضبط التي تنطبق عليها تبعية التطبيق. إذا كان من المفترض أن تكون المكتبة متاحة لجميع الإعدادات، اختَر إعدادات التنفيذ.

   

   راجِع ملف build.gradle أو build.gradle.kts في تطبيقك للتأكّد من ظهور بيان مشابه لما يلي (استنادًا إلى إعدادات الإصدار التي اخترتها):

   Groovy

     implementation files('my_path/my_lib.aar')

   Kotlin

     implementation(files("my_path/my_lib.aar"))

لاستيراد عنصر تابع في إصدار Gradle الذي يتم تشغيله خارج "استوديو Android"، أضِف مسارًا إلى العنصر التابع في ملف build.gradle أو build.gradle.kts الخاص بتطبيقك. مثلاً:

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
}

dependencies {
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar"))))
}

لمزيد من المعلومات حول إضافة برامج Gradle اعتمادية، يُرجى الاطّلاع على إضافة برامج اعتمادية للإنشاء.

تعريف مورد عام

تشمل الموارد جميع الملفات في دليل res/ الخاص بمشروعك، مثل الصور. تكون جميع المراجع في المكتبة عامة بشكلٍ تلقائي. لإتاحة جميع الموارد بشكل خاص ضمنيًا، يجب تحديد سمة واحدة على الأقل كسمة عامة.

للإعلان عن مورد عام، أضِف بيان <public> إلى ملف public.xml في مكتبتك. إذا لم يسبق لك إضافة موارد عامة، عليك إنشاء الملف public.xml في الدليل res/values/ الخاص بمكتبتك.

تنشئ عيّنة الرمز البرمجي التالية مرجعَين لسلسلة عامة بالاسمين mylib_app_name وmylib_public_string:

<resources>
    <public name="mylib_app_name" type="string"/>
    <public name="mylib_public_string" type="string"/>
</resources>

لمنع مستخدمي مكتبتك من الوصول إلى الموارد المخصّصة للاستخدام الداخلي فقط، استخدِم آلية التحديد التلقائي الخاص هذه من خلال تعريف مورد واحد أو أكثر من الموارد العامة. بدلاً من ذلك، يمكنك إخفاء جميع المراجع عن طريق إضافة علامة <public /> فارغة. لا يحدّد هذا الخيار أي محتوى على أنّه علني، بل يجعل جميع المراجع خاصة.

يجب إتاحة أي مراجع تريد أن تظل مرئية للمطوّرين الذين يستخدمون مكتبتك.

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

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

اعتبارات التطوير لوحدات المكتبة

أثناء تطوير وحدات المكتبة والتطبيقات التابعة، يجب الانتباه إلى السلوكيات والقيود التالية.

• يتم دمج المكتبات حسب ترتيب الأولوية.

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

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

• تجنُّب تعارضات دمج الموارد:

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

  في حال حدوث تعارضات بين عدة مكتبات AAR، سيتم استخدام المورد من المكتبة المدرَجة أولاً في قائمة العناصر التابعة (الأقرب إلى أعلى كتلة dependencies).

  لتجنُّب تعارض الموارد، ننصحك باستخدام بادئة أو نظام تسمية آخر متسق وفريد للوحدة (أو فريد في جميع وحدات المشروع).

• في عمليات الإنشاء المتعددة الوحدات، يتم التعامل مع تبعيات JAR على أنّها تبعيات متعدية.

  عند إضافة تبعية JAR إلى مشروع مكتبة ينتج عنه ملف AAR، تتم معالجة ملف JAR بواسطة وحدة المكتبة وتتم حزمته مع ملف AAR.

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

  يجب حل أي تعارضات في موارد Java ناتجة عن تبعيات JAR محلية في وحدة التطبيق التي تستخدم المكتبة.

• يمكن أن تعتمد وحدة المكتبة على مكتبة JAR خارجية.

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

  يُرجى العِلم أنّه يجب أن يوضّح كل من وحدة المكتبة والتطبيق التابع المكتبة الخارجية في ملفات البيان الخاصة بهما في العنصر <uses-library>.

• يجب أن يكون minSdkVersion لوحدة التطبيق مساويًا للإصدار الذي تحدّده المكتبة أو أكبر منه.

  يتم تجميع المكتبة كجزء من وحدة التطبيق التابعة، لذا يجب أن تكون واجهات برمجة التطبيقات المستخدَمة في وحدة المكتبة متوافقة مع إصدار النظام الأساسي الذي تتوافق معه وحدة التطبيق.

• ينشئ كل وحدة مكتبة فئة R خاصة به.

  عند إنشاء وحدات التطبيق التابعة، يتم تجميع وحدات المكتبة في ملف AAR ثم إضافتها إلى وحدة التطبيق. لذلك، تحتوي كل مكتبة على فئة R خاصة بها، ويتم تسميتها وفقًا لاسم حزمة المكتبة.

  يتم إنشاء فئة R التي تم إنشاؤها من الوحدة الرئيسية ووحدة المكتبة في جميع الحِزم المطلوبة، بما في ذلك حزمة الوحدة الرئيسية وحِزم المكتبات.

• قد يتضمّن نموذج المكتبة ملف إعدادات ProGuard خاصًا به.

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

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

  لإضافة قواعد ProGuard إلى مشروع المكتبة، حدِّد اسم الملف باستخدام السمة consumerProguardFiles داخل كتلة defaultConfig في ملف build.gradle أو build.gradle.kts الخاص بالمكتبة.

  على سبيل المثال، يضبط المقتطف التالي lib-proguard-rules.txt كملف إعدادات ProGuard الخاص بالمكتبة:

  Groovy

  android {
      defaultConfig {
          consumerProguardFiles 'lib-proguard-rules.txt'
      }
      ...
  }

  Kotlin

  android {
      defaultConfig {
          consumerProguardFiles("lib-proguard-rules.txt")
      }
      ...
  }

  ومع ذلك، إذا كانت وحدة المكتبة جزءًا من إصدار متعدد الوحدات يتم تجميعه في حزمة APK ولا ينشئ ملف AAR، شغِّل عملية تصغير الرمز البرمجي على وحدة التطبيق فقط التي تستخدم المكتبة. لمزيد من المعلومات حول قواعد ProGuard واستخدامها، يُرجى قراءة مقالة تصغير حجم تطبيقك وتشفيره وتحسينه.

• يُشبه اختبار وحدة المكتبة إلى حد كبير اختبار تطبيق.

  ويكمن الاختلاف الرئيسي في أنّ المكتبة والعناصر التابعة لها يتم تضمينها تلقائيًا كعناصر تابعة لملف APK الخاص بالاختبار. وهذا يعني أنّ حزمة APK التجريبية لا تتضمّن الرمز البرمجي الخاص بها فحسب، بل تتضمّن أيضًا ملف AAR الخاص بالمكتبة وجميع العناصر التابعة لها. لأنّه لا يوجد تطبيق منفصل قيد الاختبار، لا تثبِّت مهمة androidTest سوى حزمة APK الخاصة بالاختبار (وتزيل تثبيتها).

  عند دمج ملفات بيانات متعددة، يتّبع Gradle ترتيب الأولوية التلقائي ويدمج ملف بيان المكتبة في ملف البيان الرئيسي لحزمة APK الخاصة بالاختبار.

بنية ملف AAR

امتداد ملف AAR هو .aar، ونوع عنصر Maven هو aar أيضًا. الملف نفسه هو ملف ZIP. الإدخال الإلزامي الوحيد هو /AndroidManifest.xml.

يمكن أن يتضمّن ملف AAR أيضًا واحدًا أو أكثر من الإدخالات الاختيارية التالية:

• /classes.jar
• /res/
• /R.txt
• /public.txt
• /assets/
• /libs/name.jar
• /jni/abi_name/name.so (حيث abi_name هي إحدى واجهات التطبيقات الثنائية المتوافقة مع Android)
• /proguard.txt
• /lint.jar
• /api.jar
• /prefab/ لتصدير المكتبات الأصلية