إنشاء مكتبة 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 مفيد للكثيرين خاصة عندما تريد مشاركة التعليمات البرمجية مع إلا أنها لا تتيح لك تضمين موارد Android أو بيان التي تفيد كثيرًا في إعادة استخدام الرموز البرمجية في مشاريع Android. هذا الدليل على إنشاء مكتبات Android.

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

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

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

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

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

    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. اختَر الإعدادات التي تتطلب هذه التبعية أو اختَر implementation إذا كانت تنطبق على جميع الإعدادات، انقر على حسنًا.

يعدّل "استوديو Android" ملف build.gradle أو build.gradle.kts في وحدتك إلى أضف التبعية بالشكل التالي:

Groovy

  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. اختَر الإعدادات التي تتطلب هذه التبعية أو اختَر implementation إذا كانت تنطبق على جميع الإعدادات، انقر على حسنًا.

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

Groovy

  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، ثم حدد التهيئة التي ستتم التبعية إليها تنطبق. إذا كان يجب أن تكون المكتبة متاحة لجميع الإعدادات، اختَر implementation.

    إضافة تبعية AAR في هيكل المشروع مربّع حوار

    تحقَّق من ملف 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 لتطبيقك. مثلاً:

Groovy

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 في مكتبتك. إذا لم تكن قد أضفت عناوين URL عامة يجب إنشاء ملف 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 إلى مشروع مكتبة يُنتج هذه العملية، تتم معالجة 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 للمكتبة الملف:

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