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

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

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'
}