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