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

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

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

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

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

في المثال التالي، نضيف عنصرًا تابعًا ثنائيًا عن بُعد (مكتبة Macrobenchmark في 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)
   }

   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.

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

عند إنشاء تطبيقك، يتضمّن "مكوّن 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 في المستقبل.

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

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

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. عند إنشاء تطبيقك، يجمع نظام الإنشاء وحدة المكتبة ويحزّم المحتوى المجمّع الناتج في التطبيق.

يحدّد ملف الإصدار أيضًا تبعية للمكوّن الإضافي لنظام Gradle المتوافق مع Android (com.application.android). وإذا كان لديك وحدات متعددة تستخدم المكوّن الإضافي نفسه، يمكنك استخدام إصدار واحد فقط من المكوّن الإضافي في مسار فئة الإصدار على مستوى جميع الوحدات. بدلاً من تحديد الإصدار في كل من نصوص البرامج الإنشائية الخاصة بالوحدات، يجب تضمين تبعية المكوّن الإضافي في نص البرنامج الإنشائي الجذر مع الإصدار، والإشارة إلى عدم تطبيقه. تؤدي إضافة apply false إلى توجيه 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'
}