تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

أضف اسمًا مستعارًا لإصدار التبعية التي تريدها في قسم [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".
أضف اسمًا مستعارًا للتبعية في [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 في كتالوج الإصدارات وإنشاء ملفات، والسماح لها بإدارة تلك الإصدارات نيابة عنك. عرض استخدام قائمة المواد لمزيد من التفاصيل.
أضف مرجعًا إلى الاسم المستعار للتبعية إلى النص البرمجي للإصدار الوحدات التي تتطلب التبعية. تحويل الاسم المستعار' شرطات سفلية وشرطات إلى نقاط عند الإشارة إليها من نص إنشاء. نص الإصدار على مستوى الوحدة الشكل التالي:
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.

الإعدادات	السُلوك
`implementation`	تضيف Gradle التبعية إلى مسار فئة التجميع لحزم التبعية إلى ناتج الإصدار. عندما يكون تضبط تبعية `implementation`، لإعلام Gradle أنك لا تريد أن تتسرب الوحدة والاعتماد على الوحدات الأخرى في وقت التجميع. أي أن التبعية غير متاحة للوحدات الأخرى التي تعتمد على النظام الحالي واحدة. يمكن أن يؤدي استخدام تهيئة التبعية هذه بدلاً من يمكن أن تؤدي `api` إلى تحسينات كبيرة في وقت الإصدار لأنه يقلل من عدد الوحدات التي يحتاجها نظام الإصدار لإعادة التجميع. على سبيل المثال، إذا كانت `implementation` تُغيّر التبعية واجهة برمجة التطبيقات الخاصة بها، وتُعيد Gradle تجميع تلك التبعية فقط والوحدات التي تعتمد عليها بشكل مباشر. معظم التطبيقات والاختبارات أن تستخدم الوحدات هذه الإعدادات.
`api`	يضيف Gradle التبعية إلى مسار فئة التجميع وإنشاء الإخراج. عندما تتضمّن وحدة تبعية `api`، فهي لإعلام غرادل أن الوحدة تريد تصدير تلك التبعية على وحدات أخرى، حتى تكون متاحة لهم في وقت التشغيل ووقت التجميع. استخدم هذه التهيئة بحذر وفقط مع التبعيات التي تحتاج فيها إلى التصدير بشكل انتقالي إلى المستهلكين الرئيسيين الآخرين إذا كانت تؤدي تبعية `api` إلى تغيير واجهة برمجة التطبيقات الخارجية، Gradle على تجميع جميع الوحدات التي لديها إمكانية الوصول إلى تلك التبعية الوقت. يمكن أن يؤدي وجود عدد كبير من تبعيات `api` إلى زيادة وقت الإصدار بشكل كبير ما لم تكن تريد الكشف عن واجهة برمجة التطبيقات التابعة للتبعية إلى وحدة منفصلة، فينبغي أن تستخدم وحدات المكتبة بدلاً من ذلك استخدام تبعيات `implementation`.
`compileOnly`	يضيف Gradle التبعية إلى مسار فئة التجميع فقط (أي أنّه لا تتم إضافته إلى ناتج الإصدار). يكون هذا مفيدًا عندما فأنت تنشئ وحدة Android وتحتاج إلى الاعتمادية أثناء ولكن اختياري عرضه في وقت التشغيل أمر اختياري. بالنسبة على سبيل المثال، إذا كنت تعتمد على مكتبة لا تتضمّن سوى تعليقات توضيحية لوقت التجميع، وهي تُستخدم عادةً لإنشاء رمز برمجي ولكنها لا تكون مضمَّنة في أغلب الأحيان في نتيجة الإصدار، يمكنك وضع علامة `compileOnly` على تلك المكتبة. إذا استخدمت هذه التهيئة، فعندئذٍ يجب أن تكون وحدة المكتبة تضمين شرط بيئة تشغيل للتحقق مما إذا كانت التبعية ثم تغيير سلوكها بسلاسة حتى تتمكن من إذا لم يتم تقديمها. وهذا يساعد على تقليل حجم التطبيق النهائي عن طريق عدم إضافة تبعيات عابرة غير ضرورية. ملاحظة: لا يمكنك استخدام `compileOnly` بتبعيات أرشيف Android (AAR).
`runtimeOnly`	يضيف Gradle التبعية إلى ناتج الإصدار فقط، للاستخدام أثناء وقت التشغيل أي أنه لا تتم إضافته إلى مسار تصنيف التجميع. نادرًا ما يتم استخدام هذا الإعداد على Android، ولكنه يشيع استخدامه في الخادم. التطبيقات لتوفير عمليات تنفيذ التسجيل. على سبيل المثال، يمكن أن تستخدم واجهة برمجة تطبيقات للتسجيل لا تتضمن التنفيذ. ويمكن لمستخدمي تلك المكتبة إضافتها `implementation` وتتضمن تبعية `runtimeOnly` للتسجيل الفعلي التنفيذ.
`ksp kapt annotationProcessor`	توفر هذه الإعدادات المكتبات التي تعالج التعليقات التوضيحية والرموز الأخرى في التعليمات البرمجية الخاصة بك قبل تجميعها. عادةً والتحقق من صحة التعليمات البرمجية أو إنشاء تعليمة برمجية إضافية، مما يقلل من التعليمات البرمجية تحتاج إلى الكتابة. لإضافة هذه التبعية، يجب إضافتها إلى مسار الفئة الخاص بمعالج التعليقات التوضيحية باستخدام الإعدادات `ksp` أو `kapt` أو `annotationProcessor`. باستخدام هذه على تحسين أداء الإصدار من خلال فصل التجميع classpath من مسار فئة معالج التعليقات التوضيحية. وإذا وجدَت Gradle معالجات التعليقات التوضيحية على مسار فئة التجميع، فإنه يتم إلغاء تنشيطها تجنب التجميع، وهو ما يؤثر سلبًا في وقت الإنشاء (Gradle 5.0 والإصدارات الأعلى تتجاهل معالجات التعليقات التوضيحية الموجودة في التجميع classpath). يفترض المكوّن الإضافي لنظام Gradle المتوافق مع Android أن التبعية هي تعليق توضيحي إلى معالج البيانات إذا كان ملف JAR يحتوي على الملف التالي: `META-INF/services/javax.annotation.processing.Processor` إذا اكتشف المكون الإضافي معالجًا للتعليقات التوضيحية والموجود في تجميع مسار الفئة، ستنتج خطأ في الإصدار. `ksp` هو أحد معالِجات رموز Kotlin، ويتم تشغيله من خلال المحول البرمجي لـ Kotlin. `kapt` و`apt` هما أداتان منفصلتان معالجة التعليقات التوضيحية قبل تنفيذ برامج التجميع بلغة Kotlin أو Java. عند تحديد الإعدادات التي تريد استخدامها، ضع في اعتبارك التالي: إذا كان معالج الرموز متاحًا كمعالج رموز Kotlin، فاستخدم كتبعية `ksp`. راجِع النقل من kapt إلى ksp. لمزيد من التفاصيل حول استخدام معالِجات رموز Kotlin. إذا لم يكن المعالج متاحًا كمعالج رموز Kotlin: إذا كان مشروعك يتضمن مصدر Kotlin (ولكن يمكن أيضًا تضمين مصدر Java)، استخدام `kapt` لإدراجها. إذا كان مشروعك يستخدم مصدر Java فقط، استخدِم `annotationProcessor` لإدراجها. لمزيد من المعلومات عن استخدام معالجات التعليقات التوضيحية، راجع إضافة برامج معالجة التعليقات التوضيحية
`lintChecks`	استخدِم هذه الإعدادات لتضمين مكتبة تحتوي على أداة Lint. عمليات التحقّق التي تريد من Gradle تنفيذها عند إنشاء تطبيق Android مشروعك. يُرجى العِلم أنّ ملفات AAR التي تحتوي على ملف `lint.jar` سيتم تشغيل عمليات التحقّق المحدّدة في ملف `lint.jar` تلقائيًا وليس عليك إضافة تبعية `lintChecks` صريحة. يتيح لك هذا تحديد المكتبات وعمليات فحص الوبر المرتبطة بها في تقرير واحد الاعتمادية، لضمان إجراء عمليات التحقق عندما يستخدم المستهلكون المكتبة.
`lintPublish`	استخدِم هذه الإعدادات في مشاريع مكتبة Android لتضمين أداة Lint. عليك التحقّق من الحاجة إلى تجميعها في ملف `lint.jar` من خلال Gradle والحِزم في ميزة "التطبيق التلقائي للاقتراحات" وهذا يتسبب في أن المشروعات التي تستهلك AAR لتطبيق عمليات فحص الوبر أيضًا. إذا كنت تستخدم في السابق إعداد التبعية `lintChecks` لتضمين Lint في AAR المنشورة، فيجب نقل هذه التبعيات لاستخدام إعدادات `lintPublish` بدلاً من ذلك. Kotlin 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")) } Groovy 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، استخدِم ما يلي:

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Groovy

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

ومع ذلك، إذا أردت إضافة تبعية لخيار يضمّ منتجًا الصيغة ونوع التصميم، فيجب عندئذٍ إعداد اسم الإعداد:

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Groovy

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

إضافة اعتماديات implementation لاختباراتك المحلية والاختبارات المعدّة ، تبدو كما يلي:

Kotlin

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

Groovy

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.

ومن ثم، سيكون ترتيب التبعية الثابت على النحو التالي:

LIB_A
LIB_D
LIB_B
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 وحدة التحكم في المستقبل.

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

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

Kotlin

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

Groovy

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" مجموعة مساحات الاسم. البرنامج الثنائي البعيد بيان التبعية هو اختصار لما يلي:

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Groovy

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 هذه.

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Groovy

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

إذا كان لديك مشروع بوحدة واحدة، يمكنك تحديد الإصدار بشكل صريح في النص البرمجي للإنشاء على مستوى الوحدة وترك النص البرمجي للإنشاء على مستوى المشروع فارغًا:

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

Groovy

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}