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

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

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

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

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

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

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

المتطلبات الأساسية

لاستخدام المكوّن الإضافي Fused Library، استخدِم الإصدار 9.0 من AGP أو إصدارًا أحدث. تختلف سلوكيات الإصدارات السابقة من المكوّن الإضافي Fused Library ومشاكلها، وقد تم إصلاحها في الإصدار 9.0 من AGP.

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

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

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

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

Kotlin

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

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

dependencies { }

أنيق

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")
}

أنيق

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

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

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

  • يجب أيضًا تطبيق المكوّن الإضافي Maven Publish على أي وحدة تم تطبيق المكوّن الإضافي Fused Library عليها.
  • يجب أن تكتسب عملية النشر من 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"])
        }
    }
}

أنيق

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"))
    }
}

أنيق

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

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

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

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

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

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

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

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

النوع السلوك
الصفوف ستؤدي المكتبات التي تتضمّن مسار الفئة نفسه إلى تعذُّر عملية الإنشاء عند دمج المكتبة.
موارد لنظام التشغيل Android سيأخذ دمج الموارد في الاعتبار ترتيب التبعيات المحدّدة عند اختيار مورد بالاسم نفسه في موارد مختلفة.
البيانات الوصفية لملف AAR يتم دمج إصدارات البيانات الوصفية لملفات AAR من خلال منح الأولوية لأعلى قيمة من كل مكتبة تابعة. تتوفّر لغة DSL لتجاوز هذه القيم.

Kotlin

 androidFusedLibrary { aarMetadata { minCompileSdk = 21 minCompileSdkExtension = 1 } }
مراجع Java لا يُسمح بملفات موارد Java في مكتبات متعددة بمسارات متطابقة، وسيؤدي ذلك إلى تعذُّر عملية الإنشاء.

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

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

  • المشكلة رقم 454305444: يتعذّر إنشاء المكتبات التي تحتوي على قواعد ProGuard للمستهلكين والتي لا تحمل اسم "proguard.txt". تم إصلاح هذه المشكلة في الإصدار 9.1 من AGP والإصدارات الأحدث.
  • المشكلة رقم 374982739: إضافة تبعيات الملفات على ملفات ‎ .aar الأخرى
  • المشكلة رقم 231433225: لا يتوفّر دعم لدمج عناصر RenderScript وPrefab

فهم تبعيات المكتبة المدمجة

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

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