المخطط الزمني لنقل بيانات مكوّنات Android Gradle Plugin أو واجهة برمجة التطبيقات:

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

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

للحصول على سجلّ أكثر تفصيلاً لعمليات إيقاف واجهات برمجة التطبيقات في "منصة Google الإعلانية" نهائيًا أو إزالتها، يُرجى الاطّلاع على تعديلات واجهة برمجة التطبيقات في "منصة Google الإعلانية".

الإصدار 10.0 من AGP (أواخر 2026)

التغييرات والتحديثات في واجهة برمجة التطبيقات للإصدار 10.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

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

لماذا نموذج البناء الكسول؟

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

من خلال الانتقال إلى نموذج إنشاء كسول بالكامل باستخدام موفّري البيانات الكسولين (Provider<T>) وVariant API الحديثة (androidComponents {})، يتم احتساب الخصائص وعمليات ربط المهام بشكل كسول عند الطلب فقط عندما يحتاج إليها الرسم البياني النشط لتنفيذ عملية الإنشاء.

كانت واجهات برمجة التطبيقات القديمة التي ستتم إزالتها في هذا الإصدار غير متوافقة بشكل أساسي مع هذه البنية الحديثة. ويتيح إزالتها لـ AGP إمكانية توفير الدعم الكامل لميزة &quot;ذاكرة التخزين المؤقت لإعدادات Gradle&quot; وميزة &quot;عزل المشاريع&quot;، ما يؤدي إلى تحسين سرعات الإنشاء وأوقات المزامنة في &quot;استوديو Android&quot; بشكل كبير.

الاختلاف الأساسي في التصميم

كانت واجهة برمجة التطبيقات القديمة BaseVariant (applicationVariants.all {}) سريعة الاستجابة وتركز على المهام. وقد أتاحت للمطوّرين الوصول المباشر إلى مهام Gradle والإعدادات الداخلية خلال مرحلة الإعداد، ما يؤدي إلى إيقاف ميزات أداء Gradle الحديثة.

تتسم واجهة برمجة التطبيقات الجديدة الخاصة بالمتغيرات (androidComponents {}) بالتحميل الكسول والتركيز على العناصر. تستخدم هذه الواجهة Property API من Gradle على نطاق واسع وتزيل تمامًا جميع الإشارات إلى Task وTaskProvider، ما يتطلّب منك التفاعل بشكل سليم مع المدخلات والمخرجات (Variant.artifacts) بدلاً من المهام الأساسية نفسها.

المحتوى الذي ستتم إزالته واستبداله

يتم حذف جميع الواجهات والفئات السابقة المستخدَمة في DSL القديم وVariant API القديم. لإعداد نصوص البرامج الإنشائية والمكوّنات الإضافية المخصّصة، عليك نقلها من واجهات برمجة التطبيقات والعلامات التالية التي تم إيقافها نهائيًا:

تمت إزالة واجهة برمجة التطبيقات أو الميزة يجب استبدالها أو اتّخاذ إجراء بشأنها
الوصول المباشر إلى المهام:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 واجهة Artifacts API: بدلاً من جلب المهمة لتغيير سلوكها، استخدِم variant.artifacts لإلحاق الملفات الفعلية (النتائج) أو تعديلها أو استبدالها أثناء نقلها بين المهام.
تسجيل المصدر النشط:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 واجهة برمجة التطبيقات الخاصة بالمصادر: يمكنك ربط دليل الإخراج الخاص بمهمتك المخصّصة باستخدام variant.sources.java.addGeneratedSourceDirectory(...).
الوصول إلى مسار الفئة / الإعداد:
  • getCompileConfiguration()
  • getCompileClasspath()
 واجهة برمجة التطبيقات Instrumentation API: لتعديل أو فحص الرمز الثانوي (وهي حالة الاستخدام الأكثر شيوعًا للوصول إلى مسار الفئة)، استخدِم variant.instrumentation.transformClassesWith(...) باستخدام AsmClassVisitorFactory.
تغيير قيمة الخاصية بشكل فوري:
  • buildConfigField()
  • resValue()
 مثيلات `MapProperty` غير النشطة: استخدِم variant.buildConfigFields.put(...) وvariant.manifestPlaceholders.put(...).
علامات إيقاف التتبُّع:
  • android.newDsl
  • android.builtInKotlin
 لا يمكن استبدالها مباشرةً. أزِل هذه العلامات من gradle.properties، إذ يتم فرض استخدام لغة DSL الحديثة وKotlin المضمّنة بشكل صارم.
إضافات Legacy Variant API:
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
 استبدِلها بـ androidComponents.onVariants().
فلترة خيارات المنتج (الكتلة variantFilter) استبدِلها بـ androidComponents.beforeVariants() باستخدام أدوات اختيار المنتجات المتغيرة.
مكوّنات حزمة تطوير البرامج (SDK) وحزمة التطوير الأصلية (NDK):
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
 يمكنك الوصول إلى مكوّنات حزمة تطوير البرامج (SDK) باستخدام androidComponents.sdkComponents.
بيئات الاختبار:
  • deviceProvider
  • testServer
 نقل عملية تسجيل أجهزة الاختبار المخصّصة إلى الأجهزة المُدارة من Gradle
واجهات برمجة التطبيقات القديمة للتسجيل:
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 تم حذفها بدون استبدال مباشر.
Transform API استبدِل عمليات التحويل بواجهة Artifacts API وAsmClassVisitorFactory.

للوصول إلى جميع واجهات وفئات DSL البديلة وVariant API (androidComponents {})، استخدِم دائمًا العنصر gradle-api عند تطوير مكوّنات Gradle الإضافية المخصّصة أو منطق الإصدار.

خطوات نقل البيانات

للمساعدة في جعل عملية الترقية إلى الإصدار 10.0 من AGP سلسة ويمكن توقّعها، اتّبِع ممارسات النقل التالية:

  1. تشغيل &quot;مساعد ترقية&quot; Android Gradle Plugin: قبل الترقية مباشرةً إلى الإصدار 10.0، شغِّل مساعد ترقية&quot; Android Gradle Plugin الرسمي في Android Studio (Tools > AGP Upgrade Assistant). يعمل هذا المساعد على إتمام العديد من عمليات نقل DSL ونصوص البرامج الشائعة تلقائيًا، ويساعد في الحفاظ على سلوكيات الإصدار الحالية.
  2. استخدام مهارات Agent Mode في &quot;استوديو Android&quot;: يمكنك الاستفادة من مهارات الذكاء الاصطناعي (مثل مهارات ترقية &quot;مكوّن Android الإضافي لبرنامج Gradle&quot; المتوفّرة في مستودع مهارات Android) لأتمتة عملية نقل منطق الإصدار المعقّد ولغات DSL وتبسيطها داخل &quot;استوديو Android&quot;.
  3. إصلاح تحذيرات الإيقاف النهائي في الإصدار 9.x من AGP أولاً: عليك ترقية مشروعك إلى أحدث إصدار من الإصدار 9.x من AGP وحلّ جميع تحذيرات الإيقاف النهائي الحالية. بعد أن يصبح مشروعك متوافقًا مع الإصدار 9.x بدون أي تحذيرات وبدون الاعتماد على android.newDsl=false أو android.builtInKotlin=false، سيكون الانتقال إلى الإصدار 10.0 سلسًا.
  4. تدقيق المكوّنات الإضافية التابعة لجهات خارجية في Gradle: تأكَّد من ترقية المكوّنات الإضافية التابعة لجهات خارجية إلى إصدارات متوافقة مع الإصدار 10.0 من "مكوّن Android الإضافي لنظام Gradle". ستؤدي المكوّنات الإضافية التي لا تزال تعتمد على أنواع الإضافات القديمة إلى حدوث أخطاء في الإنشاء، مثل ClassCastException: ... cannot be cast to class BaseExtension.
  5. استخدام وصفات النقل الرسمية: للحصول على أمثلة معقّدة وواقعية على عملية النقل ومقارنات جنبًا إلى جنب، يُرجى الرجوع إلى مستودع gradle-recipes الرسمي على GitHub.

في ما يلي مقارنة بين الطريقتين قبل وبعد التغيير توضّح كيفية نقل البيانات من طلب البحث المسبق عن الصيغ القديمة إلى ضبط الصيغ عند الطلب باستخدام androidComponents {}:

السابق: Legacy Variant API (تمت إزالته في الإصدار 10.0 من "مكوّن Android الإضافي في Gradle")

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

بعد: Modern Variant API (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

كيفية اختبار سلوك الإصدار 10.0 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" في الإصدار 9.x

لست بحاجة إلى انتظار إصدار AGP 10.0 لبدء اختبار سلوكيات الإصدار والتحقّق من التوافق. أثناء تشغيل أي إصدار من الإصدارات 9.x من المكوّن الإضافي Android Gradle، يمكنك فرض سلوك الإصدار 10.0 من المكوّن الإضافي Android Gradle بشكل صريح من خلال التأكّد من أنّ gradle.properties يوقف أي عمليات إيقاف ويضبط علامات السلوك الصارم التالية:

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

من خلال فرض android.newDsl=true وandroid.builtInKotlin=true، يمكنك التأكّد من أنّ منطق الإصدار المخصّص والمكوّنات الإضافية التابعة لجهات خارجية متوافقة تمامًا مع متطلبات واجهة برمجة التطبيقات الصارمة في الإصدار 10.0 من "مكوّن Android الإضافي في Gradle".

إيقاف بعض المشاريع الفرعية بشكل انتقائي أثناء نقل البيانات

إذا أردت تفعيل android.newDsl=true على مستوى مشروعك بالكامل لاختبار السلوكيات الحديثة، ولكنك بحاجة إلى مزيد من الوقت لنقل مشاريع فرعية معيّنة، يمكنك إيقاف وحدات معيّنة بشكل انتقائي بدءًا من الإصدار 9.4.0-alpha04 من Android Gradle Plugin. أضِف android.newDsl.optOut إلى gradle.properties مع تحديد مسارات المشاريع:

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

إيقاف ميزة Kotlin المضمّنة بشكل انتقائي لكل وحدة

إذا أردت تفعيل Kotlin المضمّنة على مستوى مشروعك بالكامل (android.builtInKotlin=true)، ولكنك بحاجة إلى مزيد من الوقت لنقل مشاريع فرعية معيّنة من kotlin-android (أو للوحدات التي لا تتضمّن رمز Kotlin)، اضبط إعدادات هذه الوحدات على مستوى DSL بدلاً من مستوى المشروع. اضبط enableKotlin = false داخل ملف الإصدار الخاص بالوحدة:

android {
    enableKotlin = false
}

سير عمل تقديم الملاحظات والإبلاغ عن الأخطاء

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

  1. التحقّق من المشاكل الحالية: عليك أولاً التحقّق من خطأ التتبُّع العام في AGP 10.0 Variant API لمعرفة ما إذا كانت المشكلة التي تمنع الترحيل معروفة من قبل، ثم النقر على +1 للمشكلة.
  2. الإبلاغ عن واجهات برمجة التطبيقات غير المتوفّرة: إذا كانت حالة الاستخدام فريدة، يمكنك إرسال طلب للحصول على ميزة جديدة باستخدام نموذج Variant API المحدّد حتى نتمكّن من التحقيق في الأمر وتقديم المساعدة.

(مؤقت) تمت إزالة إذن الوصول إلى فئات AGP الداخلية الخاصة

تؤدي الاعتمادية على العنصر gradle الآن إلى إخفاء جميع الفئات الداخلية ومنح إذن الوصول إلى التجميع فقط للواجهات والفئات المتاحة في العنصر gradle-api. ويؤثر ذلك في تجميع المكوّنات الإضافية.

لا يمكن إضافة عنصر تابع يدويًا للوصول إلى الفئات الداخلية.

AGP 9.0 (يناير 2026)

إصدار ثابت من واجهات برمجة التطبيقات الجديدة الخاصة بحزم التطبيقات المتغيرة، وإيقاف واجهات برمجة التطبيقات القديمة

أصبحت واجهات برمجة التطبيقات الخاصة بالخيارات التي كانت في مرحلة التجربة في الإصدارَين 4.1 و4.2 ثابتة ويمكن العثور عليها في العنصر gradle-api. تم الآن إيقاف الواجهات والفئات السابقة المستخدَمة في واجهة Variant API القديمة نهائيًا، ويجب الموافقة صراحةً على استخدامها.

واجهات DSL الجديدة ثابتة، والواجهات القديمة متوقفة نهائيًا

أصبحت واجهات DSL التي كانت في مرحلة التجربة في الإصدارات 4.1 و4.2 و7.0 ثابتة الآن، وهي متوفّرة في العنصر gradle-api. تم إيقاف الواجهات والفئات السابقة المستخدَمة في DSL نهائيًا، ويجب الموافقة صراحةً على استخدامها.

لا يزال بإمكانك الوصول إلى صفوف AGP الداخلية الخاصة

تظل الفئات الداخلية الخاصة من AGP، والموجودة في عناصر أخرى، متاحة أثناء تجميع ملفات الإنشاء والمكوّنات الإضافية، ولكن لا ننصح باستخدامها لأنّها قد تتغيّر بطرق غير متوافقة في أي وقت.