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

يتيح لك نظام تصميم Gradle في "استوديو Android" إمكانية تضمين بدائل أو برامج ثنائية أو وحدات مكتبة أخرى إلى الإصدار الخاص بك كتبعيات. تشير رسالة الأشكال البيانية يمكن وضع تلك التبعيات على جهازك أو في مستودع بعيد التبعيات المنتقلة التي يفصحون عنها يتم تضمينها تلقائيًا أيضًا. تصف هذه الصفحة كيفية استخدام الاعتماديات مع مشروع Android، بما في ذلك تفاصيل حول السلوكيات وعمليات الضبط التي تقتصر على المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP). للحصول على دليل مفاهيمي أكثر تفصيلاً حول Gradle والتبعيات لديك، فيجب أن ترى أيضًا دليل Gradle لإدارة التبعية —ولكن تذكّر أن مشروع Android يجب أن يستخدم عمليات ضبط التبعية المحددة في هذه الصفحة.

إضافة تبعية لمكتبة أو مكوّن إضافي

أفضل طريقة لإضافة تبعيات الإصدار وإدارتها هي استخدام كتالوجات الإصدارات، الطريقة التي تستخدمها المشروعات الجديدة افتراضيًا. يتناول هذا القسم المواضيع الأكثر شيوعًا وأنواع الإعدادات المستخدمة في مشاريع Android يُرجى الرجوع إلى مستندات Gradle للحصول على مزيد من الخيارات. للاطّلاع على مثال عن تطبيق يستخدم كتالوجات الإصدارات، يُرجى مراجعة الآن في Android. إذا كنت قد قمت بالفعل بإعداد تبعيات بدون كتالوجات الإصدارات ولديك مشروع متعدد الوحدات، نقترح النقل.

للحصول على إرشادات حول إضافة الاعتماديات الأصلية وإدارتها (غير شائع)، يُرجى الاطّلاع على التبعيات الأصلية.

في المثال التالي، نضيف برنامجًا ثنائيًا عن بُعد. الاعتمادية (Jetpack macrobenchmark) مكتبة)، وحدة مكتبة محلية والتبعية (myLibrary) ومكوّن إضافي (المكون الإضافي لنظام Gradle المتوافق مع Android) لمشروعنا. إليك العامة الخطوات لإضافة هذه التبعيات إلى مشروعك:

1. أضف اسمًا مستعارًا لإصدار التبعية التي تريدها في قسم [versions] في ملف قائمة الإصدارات، يُسمى libs.versions.toml (ضمن الدليل gradle في عرض المشروع أو نصوص Gradle Scripts في طريقة عرض 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)
   }
   

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

ضبط التبعيات لصيغة إصدار محدّدة

تنطبق جميع الإعدادات السابقة على التبعيات على جميع صيغ الإصدار. في حال حذف بل تحتاج بدلاً من ذلك إلى الإعلان عن تبعية لبنية مجموعة بيانات مختلفة أو مصدر اختبار مجموعة، عليك كتابة الإعدادات بأحرف لاتينية كبيرة في الإعدادات في اسم نسخة الإصدار أو مجموعة مصادر الاختبار

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

إضافة اعتماديات الإصدار بدون كتالوجات الإصدارات

ننصح باستخدام كتالوجات الإصدارات لإضافة التبعيات وإدارتها، ولكن يمكن إجراء ذلك قد لا تحتاج إليها المشروعات. فيما يلي مثال على ملف إصدار لا يستخدم كتالوجات الإصدارات:

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 خبر ملاحظة على إصدار المكون الإضافي ولكن ليس لاستخدامه في الإصدار الجذر. عادةً ما يكون النص البرمجي للإصدار الجذر فارغًا باستثناء مجموعة 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'
}