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

يتيح لك نظام إنشاء 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.

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، استخدِم ما يلي:

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

ومع ذلك، إذا كنت تريد إضافة عنصر تابع لخيار يجمع بين ملف طعم المنتج ونوع الإصدار، عليك بدء اسم الإعداد:

// 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 إلى اختباراتك على الجهاز والاختبارات المستندة إلى أدوات قياس الأداء ، سيظهر الرمز على النحو التالي:

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 في المستقبل.

إضافة التبعيات في عملية الإنشاء بدون كتالوجات الإصدارات

ننصحك باستخدام كتالوجات الإصدارات لإضافة التبعيات وإدارتها، ولكن قد لا تحتاج المشاريع السهلة إليها. في ما يلي مثال على ملف إنشاء لا يستخدم قوائم الإصدارات:

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". يشير بيان الاعتماد على ملف ثنائي عن بُعد إلى ما يلي:

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 هذه.

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

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

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

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

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