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

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

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

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

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

في المثال التالي، نضيف اعتمادًا على ملف ثنائي عن بُعد (مكتبة قياس أداء برمجة التطبيقات على نطاق واسع في Jetpack) واعتمادًا على وحدة مكتبة محلية (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) تُجمِّع مجموعات المكتبات وإصداراتها. يمكنك تضمين قائمة بمواد التصنيع في قائمة الإصدارات وملفات التصميم، والسماح لها بإدارة هذه الإصدارات نيابةً عنك. راجِع مقالة استخدام فاتورة المواد للاطّلاع على التفاصيل.

  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 التبعيات إلى مسار تجميع classpath وملف ناتج الإنشاء. عندما تتضمّن الوحدة تبعية api، يعني ذلك أنّها تُعلم Gradle بأنّ الوحدة تريد تصدير هذه التبعية بشكل تصاعدي إلى الوحدات الأخرى، لكي تكون متاحة لها في وقت التشغيل ووقت الترجمة.

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

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

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

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

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

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

يفترض المكوّن الإضافي لنظام Gradle المتوافق مع Android أنّ العنصر المُستخدَم كمرجع هو معالج annotated comment إذا كان ملف JAR يحتوي على الملف التالي:

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

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

ksp هو معالج رموز Kotlin، ويتم تشغيله من خلال compiler Kotlin.

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

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

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

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

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

يُرجى العِلم أنّ حِزم AAR التي تحتوي على ملف lint.jar ستبدأ تلقائيًا عمليات التحقّق المحدّدة في ملف lint.jar هذا، وبالتالي لن تحتاج إلى إضافة تبعية lintChecks صريحة. يتيح لك ذلك تحديد المكتبات وعمليات التحقّق من الأخطاء المرتبطة بها في تبعية واحدة ، ما يضمن تنفيذ عمليات التحقّق عندما يستخدم المستخدِمون مكتبتك.
lintPublish استخدِم هذه الإعدادات في مشاريع مكتبات Android لتضمين عمليات فحص lint التي تريد أن يجمعها Gradle في ملف lint.jar ويحزِّمها في حزمة AAR. يؤدي ذلك إلى أن تطبِّق المشاريع التي تستخدِم ملف 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.6.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.6.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 والملحقات التي يستخدمها تطبيقك، وفي بعض الحالات، تقدّم أداة Play Console ملاحظات قابلة للتنفيذ بهدف حلّ هذه المشاكل.

يتم ضغط البيانات وتشفيرها باستخدام مفتاح توقيع 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" تحذيرات lint في ملف قائمة الإصدارات ومربّع حوار هيكل المشروع لحِزم 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. عند إنشاء تطبيقك، يُجمِّع نظام الإنشاء وحدة المكتبة ويُجمِّع المحتوى المجمَّع الناتج في التطبيق.

يحدِّد ملف الإنشاء أيضًا الاعتماد على المكوّن الإضافي لنظام Android Gradle (com.application.android). إذا كانت لديك وحدات متعددة تستخدِم المكوّن الإضافي نفسه، يمكنك استخدام إصدار واحد فقط من المكوّن الإضافي في مسار فئة التحميل لملف الإنشاء في جميع الوحدات. بدلاً من تحديد الإصدار في كل من نصوص ملف بدء برمجة الوحدات، يجب تضمين تبعية المكوّن الإضافي في نص بدء الإنشاء الجذر مع الإصدار، والإشارة إلى عدم تطبيقه. تؤدي إضافة apply false إلى توجيه IDE 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'
}