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

يتيح لك نظام إنشاء Gradle في Android Studio تضمين ملفَّات ثنائية خارجية أو وحدات مكتبة أخرى في عملية التصميم بصفتها ملفات تابعة. ويمكن وضع التبعيات على جهازك أو في مستودع بعيد، كما يتم تلقائيًا تضمين أي تبعيات انتقالية يُعلِن عنها. توضّح هذه الصفحة كيفية استخدام التبعيات مع مشروع Android، بما في ذلك التفاصيل حول السلوكيات والإعدادات الخاصة بمكوّن Android Gradle الإضافي (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) المنشورة التي تجمع عائلات المكتبات وإصداراتها. يمكنك تضمين 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 والتبعيات التي يستخدمها تطبيقك، وتقديم ملاحظات قابلة للتنفيذ في بعض الحالات لحلّ هذه المشاكل.

يتم ضغط البيانات وتشفيرها باستخدام مفتاح توقيع 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. عند إنشاء تطبيقك، يجمّع نظام التصميم وحدة المكتبة ويدمج المحتوى المجمَّع الناتج في التطبيق.

يكشف ملف الإصدار أيضًا عن اعتمادية على المكوّن الإضافي لنظام Gradle المتوافق مع Android (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'
}