يتيح لك نظام تصميم Gradle في "استوديو Android" إمكانية تضمين بدائل أو برامج ثنائية أو وحدات مكتبة أخرى إلى الإصدار الخاص بك كتبعيات. تشير رسالة الأشكال البيانية يمكن وضع تلك التبعيات على جهازك أو في مستودع بعيد التبعيات المنتقلة التي يفصحون عنها يتم تضمينها تلقائيًا أيضًا. تصف هذه الصفحة كيفية استخدام الاعتماديات مع مشروع Android، بما في ذلك تفاصيل حول السلوكيات وعمليات الضبط التي تقتصر على المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP). للحصول على دليل مفاهيمي أكثر تفصيلاً حول Gradle والتبعيات لديك، فيجب أن ترى أيضًا دليل Gradle لإدارة التبعية —ولكن تذكّر أن مشروع Android يجب أن يستخدم عمليات ضبط التبعية المحددة في هذه الصفحة.
إضافة تبعية لمكتبة أو مكوّن إضافي
أفضل طريقة لإضافة تبعيات الإصدار وإدارتها هي استخدام كتالوجات الإصدارات، الطريقة التي تستخدمها المشروعات الجديدة افتراضيًا. يتناول هذا القسم المواضيع الأكثر شيوعًا وأنواع الإعدادات المستخدمة في مشاريع Android يُرجى الرجوع إلى مستندات Gradle للحصول على مزيد من الخيارات. للاطّلاع على مثال عن تطبيق يستخدم كتالوجات الإصدارات، يُرجى مراجعة الآن في Android. إذا كنت قد قمت بالفعل بإعداد تبعيات بدون كتالوجات الإصدارات ولديك مشروع متعدد الوحدات، نقترح النقل.
للحصول على إرشادات حول إضافة الاعتماديات الأصلية وإدارتها (غير شائع)، يُرجى الاطّلاع على التبعيات الأصلية.
في المثال التالي، نضيف برنامجًا ثنائيًا عن بُعد.
الاعتمادية (Jetpack macrobenchmark)
مكتبة)، وحدة مكتبة محلية
والتبعية (myLibrary
) ومكوّن إضافي
(المكون الإضافي لنظام Gradle المتوافق مع Android) لمشروعنا. إليك العامة
الخطوات لإضافة هذه التبعيات إلى مشروعك:
أضف اسمًا مستعارًا لإصدار التبعية التي تريدها في قسم
[versions]
في ملف قائمة الإصدارات، يُسمىlibs.versions.toml
(ضمن الدليلgradle
في عرض المشروع أو نصوص Gradle Scripts في طريقة عرض 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) }
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 |
يضيف Gradle التبعية إلى مسار فئة التجميع وإنشاء
الإخراج. عندما تتضمّن وحدة تبعية api ، فهي
لإعلام غرادل أن الوحدة تريد تصدير
تلك التبعية على وحدات أخرى، حتى تكون متاحة لهم في
وقت التشغيل ووقت التجميع.
استخدم هذه التهيئة بحذر وفقط مع التبعيات التي
تحتاج فيها إلى التصدير بشكل انتقالي إلى المستهلكين الرئيسيين الآخرين إذا كانت
تؤدي تبعية |
compileOnly |
يضيف Gradle التبعية إلى مسار فئة التجميع فقط
(أي أنّه لا تتم إضافته إلى ناتج الإصدار). يكون هذا مفيدًا عندما
فأنت تنشئ وحدة Android وتحتاج إلى الاعتمادية أثناء
ولكن اختياري عرضه في وقت التشغيل أمر اختياري. بالنسبة
على سبيل المثال، إذا كنت تعتمد على مكتبة لا تتضمّن سوى تعليقات توضيحية لوقت التجميع، وهي تُستخدم عادةً لإنشاء رمز برمجي ولكنها لا تكون مضمَّنة في أغلب الأحيان في نتيجة الإصدار، يمكنك وضع علامة compileOnly على تلك المكتبة.
إذا استخدمت هذه التهيئة، فعندئذٍ يجب أن تكون وحدة المكتبة تضمين شرط بيئة تشغيل للتحقق مما إذا كانت التبعية ثم تغيير سلوكها بسلاسة حتى تتمكن من إذا لم يتم تقديمها. وهذا يساعد على تقليل حجم التطبيق النهائي عن طريق عدم إضافة تبعيات عابرة غير ضرورية.
ملاحظة: لا يمكنك استخدام |
runtimeOnly |
يضيف Gradle التبعية إلى ناتج الإصدار فقط، للاستخدام
أثناء وقت التشغيل أي أنه لا تتم إضافته إلى مسار تصنيف التجميع.
نادرًا ما يتم استخدام هذا الإعداد على Android، ولكنه يشيع استخدامه في الخادم.
التطبيقات لتوفير عمليات تنفيذ التسجيل. على سبيل المثال،
يمكن أن تستخدم واجهة برمجة تطبيقات للتسجيل لا تتضمن
التنفيذ. ويمكن لمستخدمي تلك المكتبة إضافتها
implementation وتتضمن
تبعية runtimeOnly للتسجيل الفعلي
التنفيذ.
|
ksp |
توفر هذه الإعدادات المكتبات التي تعالج التعليقات التوضيحية والرموز الأخرى في التعليمات البرمجية الخاصة بك قبل تجميعها. عادةً والتحقق من صحة التعليمات البرمجية أو إنشاء تعليمة برمجية إضافية، مما يقلل من التعليمات البرمجية تحتاج إلى الكتابة. لإضافة هذه التبعية، يجب إضافتها إلى مسار الفئة الخاص بمعالج التعليقات التوضيحية باستخدام الإعدادات يفترض المكوّن الإضافي لنظام Gradle المتوافق مع Android أن التبعية هي تعليق توضيحي إلى معالج البيانات إذا كان ملف JAR يحتوي على الملف التالي:
إذا اكتشف المكون الإضافي معالجًا للتعليقات التوضيحية والموجود في تجميع مسار الفئة، ستنتج خطأ في الإصدار.
عند تحديد الإعدادات التي تريد استخدامها، ضع في اعتبارك التالي:
لمزيد من المعلومات عن استخدام معالجات التعليقات التوضيحية، راجع إضافة برامج معالجة التعليقات التوضيحية |
lintChecks |
استخدِم هذه الإعدادات لتضمين مكتبة تحتوي على أداة Lint. عمليات التحقّق التي تريد من Gradle تنفيذها عند إنشاء تطبيق Android مشروعك. يُرجى العِلم أنّ ملفات AAR التي تحتوي على ملف |
lintPublish |
استخدِم هذه الإعدادات في مشاريع مكتبة Android لتضمين أداة Lint.
عليك التحقّق من الحاجة إلى تجميعها في ملف lint.jar من خلال Gradle
والحِزم في ميزة "التطبيق التلقائي للاقتراحات" وهذا يتسبب في أن المشروعات التي تستهلك
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")) } Groovydependencies { // 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') } |
ضبط التبعيات لصيغة إصدار محدّدة
تنطبق جميع الإعدادات السابقة على التبعيات على جميع صيغ الإصدار. في حال حذف بل تحتاج بدلاً من ذلك إلى الإعلان عن تبعية لبنية مجموعة بيانات مختلفة أو مصدر اختبار مجموعة، عليك كتابة الإعدادات بأحرف لاتينية كبيرة في الإعدادات في اسم نسخة الإصدار أو مجموعة مصادر الاختبار
فعلى سبيل المثال، لإضافة تبعية ثنائية عن بُعد فقط إلى ملف تعريف الارتباط "free" المنتج
النكهة باستخدام إعداد 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.5.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.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 تفحص وحدة التحكّم هذه البيانات الوصفية لتقديم تنبيهات بشأن المشاكل المعروفة في حِزم 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 وحدة التحكم في المستقبل.
إضافة اعتماديات الإصدار بدون كتالوجات الإصدارات
ننصح باستخدام كتالوجات الإصدارات لإضافة التبعيات وإدارتها، ولكن يمكن إجراء ذلك قد لا تحتاج إليها المشروعات. فيما يلي مثال على ملف إصدار لا يستخدم كتالوجات الإصدارات:
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
. عند إنشاء تطبيقك، فإن نظام التصميم
تجمع وحدة المكتبة وتضيف المحتوى المجمَّع الناتج في
التطبيق.
يكشف ملف الإصدار أيضًا عن اعتمادية على المكوّن الإضافي لنظام Gradle المتوافق مع Android
(com.application.android
). إذا كانت لديك وحدات متعددة تستخدم الوحدة نفسها
يمكن استخدام إصدار واحد فقط من المكوّن الإضافي في مسار فئة الإصدار
عبر جميع الوحدات. فبدلاً من تحديد الإصدار في كل وحدة
لإنشاء النصوص البرمجية، فيجب تضمين تبعية المكون الإضافي في النص البرمجي للإصدار الجذر
مع الإصدار، والإشارة إلى عدم تطبيقه. جارٍ إضافة apply false
خبر
ملاحظة على إصدار المكون الإضافي ولكن ليس لاستخدامه في الإصدار الجذر.
عادةً ما يكون النص البرمجي للإصدار الجذر فارغًا باستثناء مجموعة 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' }