يتيح لك نظام تصميم Gradle في "استوديو Android" تضمين برامج ثنائية خارجية أو وحدات مكتبة أخرى في تصميمك كتبعيات. ويمكن العثور على التبعيات على جهازك أو في مستودع بعيد، ويتم أيضًا تضمين أي تبعيات مؤقتة يتم الإعلان عنها تلقائيًا. توضّح هذه الصفحة كيفية استخدام التبعيات مع مشروع Android، بما في ذلك تفاصيل حول السلوكيات والتهيئات الخاصة بالمكون الإضافي لنظام Gradle المتوافق مع Android (AGP). للحصول على دليل مفاهيمي أكثر تفصيلاً حول تبعيات Gradle، عليك أيضًا الاطّلاع على دليل Gradle لإدارة التبعية، ولكن تذكّر أنّ مشروع Android يجب أن يستخدم فقط إعدادات التبعية المحددة في هذه الصفحة.
إضافة تبعية لمكتبة أو مكوّن إضافي
إن أفضل طريقة لإضافة تبعيات الإصدار وإدارتها هي استخدام كتالوجات الإصدارات، وهي الطريقة التي تستخدمها المشروعات الجديدة بشكل افتراضي. يتناول هذا القسم أنواع عمليات الضبط الأكثر شيوعًا المستخدمة في مشاريع Android، ويمكنك الرجوع إلى مستندات Gradle للاطّلاع على مزيد من الخيارات. للاطّلاع على مثال على تطبيق يستخدم كتالوجات الإصدارات، راجع تطبيق Now في Android. إذا سبق لك إنشاء تبعيات تم إعدادها بدون كتالوجات الإصدارات وكان لديك مشروع متعدد الوحدات، ننصحك بنقل البيانات.
للحصول على إرشادات حول إضافة التبعيات الأصلية وإدارتها (غير الشائعة)، راجع التبعيات الأصلية.
في المثال التالي، نضيف تبعية الثنائية
عن بُعد (مكتبة Jetpack Soft الإخبارية) وتبعية وحدة
المكتبة المحلية (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) المنشورة التي تجمع عائلات المكتبات وإصداراتها. يمكنك تضمين كائن BOM في كتالوج الإصدار وإنشاء ملفات، والسماح له بإدارة تلك الإصدارات نيابةً عنك. راجع استخدام فاتورة المواد للحصول على التفاصيل.
أضف مرجعًا إلى الاسم المستعار للتبعية إلى النص البرمجي لإنشاء الوحدات(الوحدات) التي تتطلب التبعية. قم بتحويل الشرطات السفلية والشرطات السفلية للاسم المستعار إلى نقاط عندما تشير إليه من نص إصدار. سيبدو النص البرمجي للإصدار على مستوى الوحدة كما يلي:
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 |
يضيف Gradle التبعية إلى مسار فئة التجميع وينشئ مخرجات. عندما تتضمّن وحدة اعتمادية api ، يعني ذلك إعلام Gradle بأنّ الوحدة تريد تصدير تلك الوحدة بشكل دوري إلى وحدات أخرى، لتكون متاحة لها في وقت التشغيل ووقت التجميع.
يُرجى توخّي الحذر عند استخدام هذه الإعدادات، وفقط مع الاعتماديات التي تحتاج إلى تصديرها بشكل مؤقّت إلى مستهلكين آخرين من المرحلة الرئيسية. إذا غيّرت تبعية |
compileOnly |
يضيف Gradle التبعية إلى مسار فئة التجميع فقط
(أي لا تتم إضافتها إلى ناتج الإصدار). ويكون ذلك مفيدًا عند
إنشاء وحدة Android وتحتاج إلى الاعتمادية أثناء التحويل البرمجي، ولكن يمكن توفيرها في وقت التشغيل بشكل اختياري. على سبيل المثال، إذا كنت تعتمد على مكتبة لا تتضمّن سوى تعليقات توضيحية في وقت التجميع، وتُستخدَم عادةً لإنشاء رمز ولكن لا يتم تضمينها غالبًا في نتيجة الإصدار، يمكنك وضع علامة compileOnly على تلك المكتبة.
إذا استخدمت هذه الإعدادات، يجب أن تتضمّن وحدة المكتبة شرطًا لوقت التشغيل للتحقّق من توفُّر هذه السمة الفرعية، ثم تغيير سلوكها على نحو ملائم كي تتمكّن من العمل في حال عدم توفّرها. ويساعد ذلك في تقليل حجم التطبيق النهائي عن طريق عدم إضافة عناصر اعتمادية مؤقتة ليست مهمة.
ملاحظة: لا يمكنك استخدام إعداد |
runtimeOnly |
يضيف Gradle التبعية إلى ناتج الإصدار فقط، وذلك لاستخدامها
في وقت التشغيل. أي أنه لا تتم إضافته إلى مسار تصنيف التجميع.
نادرًا ما تُستخدم هذه الطريقة على Android، ولكنها تُستخدم بشكل شائع في تطبيقات
الخادم لتوفير عمليات تنفيذ التسجيل. على سبيل المثال، يمكن للمكتبة استخدام واجهة برمجة تطبيقات خاصة بالتسجيل لا تتضمّن عملية تنفيذ. ويمكن لمستخدمي هذه المكتبة إضافتها كقائمة
تبعية على implementation وتضمين
تبعية runtimeOnly لعملية تنفيذ التسجيل
الفعلية لاستخدامها.
|
ksp |
وتوفر هذه الإعدادات مكتبات تعالج التعليقات التوضيحية والرموز الأخرى في الرمز قبل تجميعها. وعادة ما تتحقّق هذه البرامج من صحة الرمز أو تنشئ رمزًا إضافيًا، ما يقلّل من عدد الرموز التي تحتاج إلى كتابتها. لإضافة مثل هذه التبعية، يجب إضافتها إلى مسار فئة معالج التعليقات التوضيحية باستخدام الإعدادات يفترض المكوّن الإضافي لنظام Gradle المتوافق مع Android أن تكون التبعية هي معالج للتعليقات التوضيحية إذا كان ملف JAR يحتوي على الملف التالي:
إذا اكتشف المكوّن الإضافي معالج تعليقات توضيحية على مسار الفئة المجمّعة، سينتج عن ذلك خطأ في الإصدار.
عند اختيار الإعدادات المطلوب استخدامها، يجب مراعاة ما يلي:
لمزيد من المعلومات حول استخدام معالجات التعليقات التوضيحية، يمكنك الاطّلاع على إضافة معالجات التعليقات التوضيحية. |
lintChecks |
استخدِم هذه الإعدادات لتضمين مكتبة تحتوي على عمليات تحقّق من الوبر التي تريد من Gradle تنفيذها عند إنشاء مشروع تطبيقات Android. يُرجى العِلم أنّ أنظمة AAR التي تحتوي على ملف |
lintPublish |
استخدِم هذه الإعدادات في مشاريع مكتبة Android لتضمين عمليات التحقّق من الوبر التي تريد من Gradle جمعها في ملف lint.jar وحزمة في الاقتراحات المطبّقة تلقائيًا. ويؤدي ذلك إلى أن تطبّق المشروعات التي تستهلك
AAR تطبيق عمليات التحقق من الوبر هذه أيضًا. إذا كنت تستخدم في السابق
إعدادات التبعية lintChecks لتضمين
عمليات التحقق من Lint في AAR المنشور، عليك نقل بيانات تلك التبعيات
لاستخدام إعدادات lintPublish بدلاً من ذلك.
Kotlindependencies { // 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
بعد ذلك، سيكون ترتيب التبعية الثابت على النحو التالي:
LIB_A
LIB_D
LIB_B
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' }