إضافة تبعيات إلى الإصدار

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

إضافة تبعية لمكتبة أو مكوّن إضافي

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

للحصول على إرشادات حول إضافة التبعيات الأصلية وإدارتها (غير الشائعة)، راجع التبعيات الأصلية.

في المثال التالي، نضيف تبعية الثنائية عن بُعد (مكتبة Jetpack Soft الإخبارية) وتبعية وحدة المكتبة المحلية (myLibrary) وتبعية للمكوّن الإضافي (المكوِّن الإضافي لنظام Gradle المتوافق مع Android) إلى مشروعنا. فيما يلي الخطوات العامة لإضافة هذه التبعيات إلى مشروعك:

  1. أضِف اسمًا مستعارًا لنسخة التبعية التي تريدها في قسم [versions] من ملف كتالوج الإصدارات، المسمى libs.versions.toml (ضمن دليل gradle في عرض المشروع أو نصوص Gradle البرمجية في طريقة عرض Android):

    [versions]
    agp = "8.3.0"
    androidx-macro-benchmark = "1.2.2"
    my-library = "1.4"
    
    [libraries]
    ...
    
    [plugins]
    ...
    

    يمكن أن تحتوي الأسماء المستعارة على شرطات أو شرطات سفلية. تنشئ هذه الأسماء المستعارة قيمًا متداخلة يمكنك الرجوع إليها في البرامج النصية لإنشاء النصوص. تبدأ المراجع باسم الكتالوج، وهو الجزء libs من libs.versions.toml. عند استخدام كتالوج إصدار واحد، ننصح بالاحتفاظ بالقيمة التلقائية "libs".

  2. أضِف اسمًا مستعارًا للتبعية في قسم [libraries] (للبرامج الثنائية البعيدة أو وحدات المكتبة المحلية) أو [plugins] (للمكوّنات الإضافية) في الملف libs.versions.toml.

    [versions]
    ...
    
    [libraries]
    androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
    my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
    
    [plugins]
    androidApplication = { id = "com.android.application", version.ref = "agp" }
    

    تتوفّر بعض المكتبات في فاتورة المواد المنشورة (BOM) المنشورة التي تجمع عائلات المكتبات وإصداراتها. يمكنك تضمين كائن BOM في كتالوج الإصدار وإنشاء ملفات، والسماح له بإدارة تلك الإصدارات نيابةً عنك. راجع استخدام فاتورة المواد للحصول على التفاصيل.

  3. أضف مرجعًا إلى الاسم المستعار للتبعية إلى النص البرمجي لإنشاء الوحدات(الوحدات) التي تتطلب التبعية. قم بتحويل الشرطات السفلية والشرطات السفلية للاسم المستعار إلى نقاط عندما تشير إليه من نص إصدار. سيبدو النص البرمجي للإصدار على مستوى الوحدة كما يلي:

    Kotlin

    plugins {
      alias(libs.plugins.androidApplication)
    }
    
    dependencies {
      implementation(libs.androidx.benchmark.macro)
      implementation(libs.my.library)
    }
    

    رائع

    plugins {
      alias 'libs.plugins.androidApplication'
    }
    
    dependencies {
      implementation libs.androidx.benchmark.macro
      implementation libs.my.library
    }
    

    تتضمن مراجع المكوّنات الإضافية plugins بعد اسم الكتالوج، بينما تتضمّن مراجع الإصدارات versions بعد اسم الكتالوج (مراجع الإصدار غير شائعة، ويمكنك مراجعة التبعيات التي لها أرقام الإصدارات نفسها للحصول على أمثلة على مراجع الإصدار). لا تشتمل مراجع المكتبة على مؤهِّل libraries، وبالتالي لا يمكنك استخدام versions أو plugins في بداية الاسم المستعار للمكتبة.

ضبط التبعيات

داخل كتلة dependencies، يمكنك تعريف مكتبة تبعية على المكتبة باستخدام إعداد من بين عدة إعدادات تبعية مختلفة (مثل implementation المعروض سابقًا). تزود كل تهيئة تبعية Gradle بتعليمات مختلفة حول كيفية استخدام التبعية. يصف الجدول التالي كل إعداد من الإعدادات التي يمكنك استخدامها للتبعية في مشروع Android الخاص بك.

الإعدادات السُلوك
implementation يضيف Gradle التبعية إلى مسار فئة التجميع ويحزم التبعية إلى مخرجات الإصدار. عندما تضبط وحدتك تبعية implementation، يعني ذلك إعلام Gradle بأنّك لا تريد أن تسرّب الوحدة التبعية إلى وحدات أخرى في وقت التجميع. ويعني ذلك أنّ الاعتمادية غير متاحة للوحدات الأخرى التي تعتمد على الوحدة الحالية.

قد يؤدي استخدام إعدادات الاعتمادية هذه بدلاً من السمة api إلى إجراء تحسينات كبيرة على مدة الإصدار، لأنّه يقلل عدد الوحدات التي يحتاج نظام الإصدار إلى إعادة تجميعها. على سبيل المثال، إذا تغيّرت تبعية implementation واجهة برمجة التطبيقات الخاصة بها، لن تجمع Gradle سوى تلك التبعية والوحدات التي تعتمد عليها بشكل مباشر. يجب أن تستخدم معظم وحدات التطبيقات والاختبار هذه الإعدادات.

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

يُرجى توخّي الحذر عند استخدام هذه الإعدادات، وفقط مع الاعتماديات التي تحتاج إلى تصديرها بشكل مؤقّت إلى مستهلكين آخرين من المرحلة الرئيسية. إذا غيّرت تبعية api واجهة برمجة التطبيقات الخارجية الخاصة بها، تعيد Gradle تجميع جميع الوحدات التي يمكنها الوصول إلى تلك الاعتمادية في وقت التجميع. يمكن أن يؤدي توفُّر عدد كبير من العناصر الاعتمادية api إلى زيادة كبيرة في وقت الإنشاء. ما لم تكن تريد عرض واجهة برمجة التطبيقات التابعة للتبعية في وحدة منفصلة، يجب أن تستخدم وحدات المكتبة تبعيات implementation بدلاً من ذلك.

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

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

ملاحظة: لا يمكنك استخدام إعداد compileOnly مع تبعيات أرشيف Android (AAR).

runtimeOnly يضيف Gradle التبعية إلى ناتج الإصدار فقط، وذلك لاستخدامها في وقت التشغيل. أي أنه لا تتم إضافته إلى مسار تصنيف التجميع. نادرًا ما تُستخدم هذه الطريقة على Android، ولكنها تُستخدم بشكل شائع في تطبيقات الخادم لتوفير عمليات تنفيذ التسجيل. على سبيل المثال، يمكن للمكتبة استخدام واجهة برمجة تطبيقات خاصة بالتسجيل لا تتضمّن عملية تنفيذ. ويمكن لمستخدمي هذه المكتبة إضافتها كقائمة تبعية على implementation وتضمين تبعية runtimeOnly لعملية تنفيذ التسجيل الفعلية لاستخدامها.
ksp
kapt
annotationProcessor

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

لإضافة مثل هذه التبعية، يجب إضافتها إلى مسار فئة معالج التعليقات التوضيحية باستخدام الإعدادات ksp أو kapt أو annotationProcessor. يؤدي استخدام هذه الإعدادات إلى تحسين أداء الإصدار من خلال فصل مسار فئة التجميع عن مسار فئة معالج التعليقات التوضيحية. إذا عثر نظام Gradle على معالجات التعليقات التوضيحية على مسار فئة التجميع، سيتم إيقاف تجنب التجميع، ما يؤثر سلبًا في وقت الإصدار (يتجاهل Gradle 5.0 والإصدارات الأحدث معالجات التعليقات التوضيحية الموجودة في مسار فئة التجميع).

يفترض المكوّن الإضافي لنظام Gradle المتوافق مع Android أن تكون التبعية هي معالج للتعليقات التوضيحية إذا كان ملف JAR يحتوي على الملف التالي:

META-INF/services/javax.annotation.processing.Processor

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

ksp هو معالج رموز Kotlin، ويتم تشغيله بواسطة المحول البرمجي لـ Kotlin.

kapt وapt هما أداتان منفصلتان تعالجان التعليقات التوضيحية قبل تنفيذ برامج التحويل البرمجي لـ Kotlin أو Java.

عند اختيار الإعدادات المطلوب استخدامها، يجب مراعاة ما يلي:

  • إذا كان المعالِج متاحًا كمعالج رموز Kotlin، يمكنك استخدامه كمعالج بيانات ksp. راجِع نقل البيانات من kapt إلى ksp للحصول على تفاصيل عن استخدام معالِجات رموز Kotlin.
  • إذا لم يكن المعالِج متاحًا كمعالج رموز Kotlin:
    • إذا كان مشروعك يتضمّن مصدر Kotlin (ولكن يمكن أن يتضمّن أيضًا مصدر Java)، استخدِم kapt لتضمينه.
    • إذا كان مشروعك يستخدم مصدر Java فقط، استخدِم annotationProcessor لتضمينه.

لمزيد من المعلومات حول استخدام معالجات التعليقات التوضيحية، يمكنك الاطّلاع على إضافة معالجات التعليقات التوضيحية.

lintChecks

استخدِم هذه الإعدادات لتضمين مكتبة تحتوي على عمليات تحقّق من الوبر التي تريد من Gradle تنفيذها عند إنشاء مشروع تطبيقات Android.

يُرجى العِلم أنّ أنظمة AAR التي تحتوي على ملف lint.jar ستجري تلقائيًا عمليات تحقّق محدّدة في ملف lint.jar، وليس عليك إضافة سمة lintChecks بشكل صريح. ويتيح لك ذلك تعريف المكتبات وعمليات فحص الوبر المرتبطة بها في تبعية واحدة، ما يضمن تنفيذ عمليات الفحص عندما يستخدم المستهلكون مكتبتك.

lintPublish استخدِم هذه الإعدادات في مشاريع مكتبة Android لتضمين عمليات التحقّق من الوبر التي تريد من Gradle جمعها في ملف lint.jar وحزمة في الاقتراحات المطبّقة تلقائيًا. ويؤدي ذلك إلى أن تطبّق المشروعات التي تستهلك AAR تطبيق عمليات التحقق من الوبر هذه أيضًا. إذا كنت تستخدم في السابق إعدادات التبعية lintChecks لتضمين عمليات التحقق من Lint في AAR المنشور، عليك نقل بيانات تلك التبعيات لاستخدام إعدادات lintPublish بدلاً من ذلك.

Kotlin

dependencies {
  // Executes lint checks from the ":checks" project at build time.
  lintChecks(project(":checks"))
  // Compiles lint checks from the ":checks-to-publish" into a
  // lint.jar file and publishes it to your Android library.
  lintPublish(project(":checks-to-publish"))
}

رائع

dependencies {
  // Executes lint checks from the ':checks' project at build time.
  lintChecks project(':checks')
  // Compiles lint checks from the ':checks-to-publish' into a
  // lint.jar file and publishes it to your Android library.
  lintPublish project(':checks-to-publish')
}

ضبط التبعيات لنسخة إصدار معيّنة

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

على سبيل المثال، لإضافة تبعية ثنائية عن بُعد إلى نكهة المنتج "المجانية" فقط باستخدام الإعدادات implementation، استخدِم الخطوات التالية:

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

رائع

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

ومع ذلك، إذا أردت إضافة سمة تابعة لخيار منتج يجمع بين نكهة المنتج ونوع التصميم، عليك إعداد اسم الإعدادات:

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

رائع

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

لإضافة اعتماديات implementation للاختبارات المحلية والاختبارات الآلية، يبدو ذلك على النحو التالي:

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.5.1")
}

رائع

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
}

ومع ذلك، هناك بعض التكوينات غير منطقية في هذه الحالة. على سبيل المثال، نظرًا لأن الوحدات الأخرى لا يمكن أن تعتمد على androidTest، ستتلقى التحذير التالي إذا كنت تستخدم الإعداد androidTestApi:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

ترتيب التبعية

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

على سبيل المثال، إذا كان مشروعك يُعلن عن ما يلي:

  • تعتمد على LIB_A وLIB_B (بهذا الترتيب)
  • وتعتمد LIB_A على LIB_C وLIB_D (بهذا الترتيب)
  • وتعتمد LIB_B أيضًا على LIB_C

بعد ذلك، سيكون ترتيب التبعية الثابت على النحو التالي:

  1. LIB_A
  2. LIB_D
  3. LIB_B
  4. LIB_C

يضمن ذلك أنّه يمكن لكل من LIB_A وLIB_B إلغاء LIB_C، ويظل LIB_D أعلى من LIB_B لأنّ LIB_A (الذي يعتمد على ذلك) له أولوية أعلى من LIB_B.

لمزيد من المعلومات حول كيفية دمج البيانات من مصادر/تبعيات المشروع المختلفة، يُرجى الاطّلاع على دمج ملفات بيان متعددة.

المعلومات المتعلقة بالاعتمادية على Play Console

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

يتم ضغط البيانات وتشفيرها باستخدام مفتاح توقيع Google Play وتخزينها في مجموعة التوقيع لتطبيق الإصدار الخاص بك. ننصحك بالاحتفاظ بملف الملحقات هذا لتوفير تجربة إيجابية وآمنة للمستخدم. يمكنك إيقاف الميزة من خلال تضمين المجموعة التالية في dependenciesInfo في ملف build.gradle.kts الخاص بالوحدة.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

للاطّلاع على مزيد من المعلومات حول سياساتنا والمشاكل المحتملة المتعلقة بالملحقات، راجِع صفحة الدعم حول استخدام حِزم تطوير برامج (SDK) تابعة لجهات خارجية في تطبيقك.

إحصاءات حِزم SDK

يعرض "استوديو Android" تحذيرات من برامج الوبر في ملف كتالوج الإصدار ومربع حوار بنية المشروع لحِزم SDK المتاحة للجميع في أداة Google Play SDK Index عند حدوث المشاكل التالية:

  • يرى المطوِّرون أنّ حِزم SDK قديمة.
  • تنتهك حِزم SDK سياسات Play.

تشير التحذيرات إلى ضرورة تعديل تلك التبعيات، لأنّ استخدام إصدارات قديمة قد يمنعك من النشر على Google Play Console في المستقبل.

إضافة تبعيات الإصدار بدون كتالوجات الإصدارات

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

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

رائع

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

يُعلن ملف الإصدار هذا عن تبعية للإصدار 12.3 من مكتبة "app-magic" داخل مجموعة مساحات الاسم "com.example.android". يعد إعلان التبعية الثنائية عن بُعد اختصارًا لما يلي:

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

رائع

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

يكشف ملف الإصدار أيضًا عن تبعية على وحدة مكتبة Android باسم "mylibrary"، ويجب أن يتطابق هذا الاسم مع اسم المكتبة المحدّد بعلامة include: في ملف settings.gradle.kts. عند إنشاء تطبيقك، يجمع نظام الإصدار وحدة المكتبة ويحزم المحتوى المجمّع الناتج في التطبيق.

يكشف ملف الإصدار أيضًا عن اعتمادية المكوِّن الإضافي لنظام Gradle المتوافق مع Android (com.application.android). وإذا كانت لديك وحدات متعددة تستخدم المكوّن الإضافي نفسه، يمكنك استخدام إصدار واحد فقط من المكوِّن الإضافي على مسار فئة الإصدار في جميع الوحدات. فبدلاً من تحديد الإصدار في كل نصوص برمجية لإنشاء الوحدة، يجب عليك تضمين تبعية المكون الإضافي في النص البرمجي لإنشاء الجذر مع الإصدار والإشارة إلى عدم تطبيقه. عند إضافة apply false، يكون بإمكان Gradle ملاحظة إصدار المكون الإضافي وليس استخدامه في البنية الجذر. يكون عادةً النص البرمجي لإنشاء الجذر فارغًا باستثناء مجموعة plugins هذه.

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

رائع

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

إذا كان لديك مشروع مؤلف من وحدة واحدة، يمكنك تحديد الإصدار بشكل صريح في النص البرمجي للإصدار على مستوى الوحدة وترك النص البرمجي للإصدار على مستوى المشروع فارغًا:

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

رائع

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}