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

يتيح لك نظام الإصدار 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_D) لها أولوية أعلى من 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'
}