تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

إضافة مكتبة أو مورد تابع لإضافة

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

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

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

أضِف اسمًا مستعارًا لإصدار التبعية الذي تريده في القسم [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".
أضِف اسمًا مستعارًا للعنصر التابع في القسم [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) تجمع مجموعات المكتبات وإصداراتها. يمكنك تضمين قائمة مواد في كتالوج الإصدارات وملفات الإنشاء، والسماح لها بإدارة هذه الإصدارات نيابةً عنك. لمزيد من التفاصيل، راجِع مقالة استخدام قائمة المواد.
أضِف مرجعًا إلى الاسم المستعار للعنصر التابع في نص برمجة الإصدار الخاص بالوحدات التي تتطلّب العنصر التابع. حوِّل الشرطات السفلية والشرطات العادية في الاسم المستعار إلى نقاط عند الإشارة إليه من نص برمجي خاص بالإنشاء. سيبدو نص البرمجة الخاص بالإنشاء على مستوى الوحدة النمطية على النحو التالي:
Kotlin
plugins { alias(libs.plugins.androidApplication) } dependencies { implementation(libs.androidx.benchmark.macro) implementation(libs.my.library) }
Groovy
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`	استخدِم هذا الإعداد لتضمين مكتبة تحتوي على عمليات التحقّق من lint التي تريد أن ينفّذها Gradle عند إنشاء مشروع تطبيق Android. يُرجى العِلم أنّ ملفات AAR التي تحتوي على ملف `lint.jar` ستنفّذ تلقائيًا عمليات التحقّق المحدّدة في ملف `lint.jar` هذا، ولن تحتاج إلى إضافة تبعية `lintChecks` صريحة. يتيح لك ذلك تحديد المكتبات وعمليات فحص lint المرتبطة بها في تبعية واحدة، ما يضمن تنفيذ عمليات الفحص عند استخدام المستهلكين لمكتبتك.
`lintPublish`	استخدِم هذا الإعداد في مشاريع مكتبات Android لتضمين عمليات التحقّق من lint التي تريد أن يجمعها Gradle في ملف `lint.jar` ويحزّمها في ملف AAR. ويؤدي ذلك إلى تطبيق عمليات فحص lint هذه أيضًا على المشاريع التي تستخدم ملف 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")) } Groovy 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")
}

Groovy

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

Groovy

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

Groovy

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

بعد ذلك، سيكون ترتيب التبعيات المسطّح على النحو التالي:

LIB_A
LIB_D
LIB_B
LIB_C

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

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

معلومات التبعية في Play Console

عند إنشاء تطبيقك، يتضمّن "مكوّن Android الإضافي في Gradle" بيانات وصفية توضّح البرامج الاعتمادية للمكتبة التي يتم تجميعها في تطبيقك. وعند تحميل تطبيقك، يفحص 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" تحذيرات lint في ملف قائمة الإصدارات ومربّع حوار بنية المشروع لحِزم SDK المتاحة للجميع في Google Play SDK Index عند حدوث المشاكل التالية:

يضع مؤلفو حِزم SDK علامة على أنّها قديمة.
تنتهك حِزم تطوير البرامج (SDK) سياسات Play.
تحتوي حِزم SDK على ثغرات أمنية معروفة.
تم إيقاف حِزم SDK نهائيًا من قِبل مؤلفيها.

تشير التحذيرات إلى أنّه عليك تعديل هذه العناصر التابعة، لأنّ استخدام إصدارات قديمة قد يمنعك من النشر على 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"))
}

Groovy

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

Groovy

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

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

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

Kotlin

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

Groovy

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

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

Kotlin

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

Groovy

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