إنشاء مكتبة Android

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   رائع

     plugins {
         id 'com.android.application'
     }
     

   Kotlin

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

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

   رائع

     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، يُرجى الاطّلاع على مستودعات 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 التبعية في القائمة.
   
   

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

   

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

   رائع

     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 /> فارغة. يؤدي ذلك إلى عدم وضع علامة "علنية" على أي محتوى وجعل جميع الموارد خاصة.

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

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

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

اعتبارات التطوير لمكوّنات المكتبة

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

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

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

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

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

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

  لتجنّب تعارض الموارد، استخدِم فئات R غير قابلة للنقل. إذا لم يكن ذلك ممكنًا، ففكر في استخدام بادئة أو نظام تسمية متسق آخر فريد للوحدة (أو يكون فريدًا عبر جميع وحدات المشروع).

• في الإصدارات المتعددة الوحدات، يتم التعامل مع تبعيات JAR كتبعيات انتقالية.

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

  ومع ذلك، إذا كان مشروعك يتضمّن وحدة مكتبة يستخدمها ملف APK ، تتعامل وحدة التطبيق مع العنصر الاعتمادي JAR المحلي للمكتبة على أنّه ملف APK عنصر اعتمادي ناتج. في هذه الحالة، تتم معالجة 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 للمكتبة:

  رائع

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

  Kotlin

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

  ومع ذلك، إذا كانت وحدة المكتبة جزءًا من عملية إنشاء متعددة الوحدات يتم compilingها في حزمة 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 أحد واجهات التطبيق الثنائية (ABI) المتوافقة مع Android)
• /proguard.txt
• /lint.jar
• /api.jar
• ‫/prefab/ من أجل تصدير مكتبات الأصلية