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

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

عند إنشاء تطبيقك، يتضمّن 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.
• تحتوي حِزم 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'
}