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

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