إنشاء مكتبة Android

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

ومع ذلك، بدلاً من تجميع مكتبة Android في ملف APK يعمل على أحد الأجهزة، يتم تجميع هذا الملف على عكس ملفات 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")

Kotlin

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

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

والطريقة المقترَحة لمشاركة التبعيات (JARs و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، أدخِل المسار إلى ملف 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"])
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

بنية ملف AAR

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

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