إنشاء مكتبة Android

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

وبدلاً من دمج مكتبة Android في ملف APK يتم تشغيله على أحد الأجهزة، يتم تجميعه في ملف أرشيف Android (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 {
         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" ملف build.gradle أو build.gradle.kts الخاص بالوحدة لإضافة التبعية، على النحو التالي:

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

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

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

والطريقة المقترحة لمشاركة التبعيات (JARs و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، أدخِل المسار إلى ملف AAR أو JAR، ثم اختَر الإعدادات التي تنطبق عليها الاعتمادية. إذا كانت المكتبة يجب أن تكون متاحة لجميع الإعدادات، اختَر إعدادات الاستخدام.

   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• يمكن أن تتضمن وحدة المكتبة ملف إعداد ProGuard الخاص بها.

  إذا كان لديك مشروع مكتبة تستخدمه لإنشاء AAR ونشره، يمكنك إضافة ملف إعداد ProGuard إلى إعدادات تصميم مكتبتك. فإذا فعلت ذلك، فسيطبّق المكوّن الإضافي لنظام Gradle المتوافق مع Android قواعد 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")
      }
      ...
  }

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

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

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

  عند دمج عدة ملفات بيان، تتّبع 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/ لتصدير المكتبات الأصلية