إنشاء مكتبة 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 script.
  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")

Kotlin

  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'

Kotlin

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

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

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

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

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

    إضافة تبعية 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"])
}

Kotlin

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 أيضًا واحدًا أو أكثر من الادخالات الاختيارية التالية: