نشر عدة مكتبات Android كمكتبة واحدة باستخدام "المكتبة المدمجة"

في المشاريع التي تتضمّن العديد من الوحدات، قد يكون من الصعب توزيع مكتبات Android على المستخدمين مع محاولة الحفاظ على بنية واضحة للمشروع. في كثير من الحالات، يجب نشر عدد أكبر بكثير من المكتبات مقارنةً بالعدد المطلوب.

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

ملاحظة: يمكنك الاطّلاع على وصفة Gradle لمكوّن Fused Library الإضافي التي توفّر خطوات لإعداد مكتبة مدمجة وإرشادات عملية أكثر.

يمكن أن يؤدي التوزيع كمكتبة واحدة إلى تحقيق المزايا التالية:

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

إنشاء مكتبة مدمجة

لإنشاء مكتبة مدمجة، عليك إنشاء وحدة Android جديدة وإضافة التبعيات ثم نشر المكتبة المدمجة.

ملاحظة مهمة: لاستخدام مكوّن Fused Library الإضافي، استخدِم الإصدار 9.0 أو إصدارًا أحدث من "مكوّن Android الإضافي في Gradle".

إضافة وحدة مكتبة مدمجة جديدة

لاستخدام المكوّن الإضافي، يجب إضافة وحدة Android جديدة إلى مشروعك:

في هذا المثال، سيتم تسمية وحدة المكتبة المدمجة myFusedLibrary.

1. فعِّل إمكانية استخدام المكتبة المدمجة من خلال إضافة android.experimental.fusedLibrarySupport=true إلى ملف gradle.properties.
2. أضِف include(":myFusedLibrary") إلى ملف settings.gradle.kts.
3. أضِف android-fusedlibrary = { id = "com.android.fused-library", version.ref = "agp" } ضمن القسم [plugins] في الملف gradle/libs.versions.toml.
4. أضِف alias(libs.plugins.android.fusedlibrary) apply false في قسم المكوّنات الإضافية ضمن ملف build.gradle.kts ذي المستوى الأعلى.
5. لإنشاء الوحدة myFusedLibrary، أنشئ دليلاً جديدًا باسم myFusedLibrary من خلال النقر على زر الماوس الأيمن على "تطبيقي" (My Application) > جديد (New) > دليل (Directory).
6. أنشئ ملف build.gradle.kts في وحدة myFusedLibrary من خلال النقر على زر الماوس الأيمن على وحدة myFusedLibrary > جديد (New) > ملف (File).
7. الصِق ما يلي في ملف myFusedLibrary/build.gradle.kts:

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

androidFusedLibrary {
    namespace = "com.example.myFusedLibrary"
    minSdk = 21
}

dependencies { }

Groovy

plugins {
    id 'com.android.fused-library'
}

androidFusedLibrary {
    namespace 'com.example.myFusedLibrary'
    minSdk 21
}

dependencies {

}

إضافة حِزم تابعة

تتمثّل الوظيفة الأساسية للمكتبة المدمجة في تجميع التبعيات. يتيح المكوّن الإضافي إضافة تبعيات المشاريع المحلية والمكتبات الخارجية. لتحديد التبعيات المطلوب تجميعها، استخدِم إعدادات include. لا يتم تضمين التبعيات الانتقالية في الحزمة.

مثلاً:

Kotlin

dependencies {
    include(project(":image-rendering"))
    include("mycoolfonts:font-wingdings:5.0")
}

Groovy

dependencies {
    include project(':image-rendering')
    include 'mycoolfonts:font-wingdings:5.0'
}

ملاحظة: إذا تم تحديد عنصر تابع باستخدام عبارة include يعتمد على مشروع مكتبة Android محلي، يجب نشر مشروع مكتبة Android المحلي إلى مستودع تم ضبطه محليًا. لمزيد من المعلومات، يُرجى الاطّلاع على نشر مكتبتك

نشر مكتبتك المدمجة

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

• يجب أيضًا تطبيق Maven Publish Plugin على أي وحدة تم تطبيق Fused Library Plugin عليها.
• يجب أن يكون الإصدار مشتقًا من fusedLibraryComponent لأنّ ذلك يوفّر الاعتماديات المطلوبة لتجميع عنصر مكتبة مدمجة.

في ما يلي مثال على إعدادات المنشورات:

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

androidFusedLibrary { … }

dependencies { … }

publishing {
    publications {
        register<MavenPublication>("release") {
             groupId = "my-company"
             artifactId = "my-fused-library"
             version = "1.0"
             from(components["fusedLibraryComponent"])
        }
    }
}

Groovy

plugins {
    id 'com.android.fused-library'
    id 'maven-publish'
}

androidFusedLibrary { … }

dependencies { … }

publishing {
    publications {
        release(MavenPublication) {
            groupId = "my-company"
            artifactId = "my-fused-library"
            version = "1.0"
            afterEvaluate {
            from components.fusedLibraryComponent
        }
    }
}

نشر المكتبة المدمجة لإجراء الاختبار

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

لنشر عناصر مكتبة مدمجة في مستودع محلي، حدِّد إعدادًا مشابهًا لما يلي:

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

repositories {
    maven {
        name = "myLocalRepo"
        url = uri(layout.buildDirectory.dir("myLocalRepo"))
    }
}

Groovy

plugins {
    id 'com.android.fused-library'
    id 'maven-publish'
}

repositories {
    maven {
        name 'myLocalRepo'
        url layout.buildDirectory.dir('myLocalRepo')
    }
}

تحميل مكتبتك المدمجة

لتوزيع مكتبتك المدمجة، يُرجى الاطّلاع على تحميل مكتبتك.

السلوك وإجراءات الوقاية

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

• لا يمكن نشر المكتبات المدمجة إلا كعنصر مكتبة Android AAR ليتم إضافتها كمكتبة يَعتمد عليها تشغيل التطبيق.
• لا يمكن دمج المكتبات التي تستخدم ربط البيانات.
• لا يمكنك دمج أنواع إصدارات ونكهات منتجات متعددة في مكتبة واحدة مدمجة. أنشِئ مكتبات مدمجة منفصلة لكل صيغة.

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

النوع	السُلوك
الصفوف	ستؤدي المكتبات التي تتضمّن مسار فئة مطابقًا إلى حدوث خطأ في الإنشاء عند دمج المكتبة.
موارد لنظام التشغيل Android	سيراعي دمج الموارد ترتيب العناصر التابعة المحدَّد عند اختيار مورد بالاسم نفسه في حزمة مختلفة.
AAR Metadata	يتم دمج إصدارات بيانات AAR الوصفية من خلال منح الأولوية لأعلى قيمة من كل مكتبة تابعة. يتوفّر DSL لإلغاء هذه القيم. Kotlin androidFusedLibrary { aarMetadata { minCompileSdk = 21 minCompileSdkExtension = 1 } }
مراجع Java	لا يُسمح بملفات موارد Java في مكتبات متعددة ذات مسارات متطابقة، وسيؤدي ذلك إلى تعذُّر إنشاء التطبيق.

المشاكل المعروفة

‫Fused Library هي إضافة جديدة، وهناك مشاكل معروفة نعمل على حلّها لتلبية جميع حالات الاستخدام.

• يتعذّر إنشاء ملفات JAR المصدر
• إضافة تبعيات الملفات على ملفات .aar أخرى
• لا تتوفّر إمكانية دمج عناصر RenderScript وPrefab

تجريبي: يقتصر نشر وحدة المكتبة المدمجة على نشرها كمكتبة خارجية. لا يمكن إضافة تبعية مشروع إلى مشروع مكتبة مدمجة محلية في وحدة أخرى، سواء كانت وحدة تطبيق Android أو وحدة مكتبة Android. لا يسمح المكوّن الإضافي بنشر سوى وحدات المكتبة المدمجة. لا يتيح Studio استخدام المشاريع مباشرةً بشكل كامل. يمكن إيقاف القيود المفروضة على النشر فقط من خلال إضافة android.experimental.fusedLibrarySupport.publicationOnly=false إلى ملف gradle.properties.

فهم العناصر التابعة لمكتبة مدمجة

لا تحتوي المكتبة المدمجة على مصادر وتستخدم مكتبات Android كمصدر وحيد لها، لذا من المهم معرفة مصدر كل عنصر. لعرض قائمة بالاعتماديات التي يتم دمجها في العنصر الناتج والاعتماديات اللازمة لإنشاء العنصر، شغِّل مهمة gradle :report على المكتبة المدمجة. تنشئ المهام تقرير JSON يتم حفظه في الدليل build/reports الخاص بالمكتبة المدمجة.

للحصول على معلومات إضافية ذات صلة بتبعيات المكوّنات الإضافية الداخلية، شغِّل المهمة gradle :dependencies لعرض حالة إعدادات المكوّنات الإضافية.