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

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

إضافة تبعية لمكتبة أو مكوّن إضافي

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

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

في المثال التالي، تتم إضافة تبعية ثنائية عن بُعد (مكتبة Jetpack Macrobenchmark) وتبعية وحدة المكتبة المحلية (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

عند إنشاء تطبيقك، يتضمّن المكوّن الإضافي لنظام Gradle المتوافق مع Android بيانات وصفية تصف تبعيات المكتبة التي يتم تجميعها في تطبيقك. وعند تحميل تطبيقك، تفحص 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 سياسات Google 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'
}