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

تحتوي هذه الصفحة على ملاحظات إصدار للإصدارات التجريبية من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" (AGP).

الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

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

للتحديث إلى الإصدار 9.0.0-beta04 من المكوّن الإضافي لنظام Gradle المتوافق مع Android، استخدِم مساعد ترقية المكوّن الإضافي لنظام Android Gradle في الإصدار 3 من تحديثات Android Studio Otter | 2025.2.3.

يساعد "مساعد ترقية" Android Gradle Plugin في الحفاظ على السلوكيات الحالية عند ترقية مشروعك عند الحاجة، ما يتيح لك ترقية مشروعك لاستخدام الإصدار 9.0 من Android Gradle Plugin، حتى إذا لم تكن مستعدًا لاستخدام جميع الإعدادات التلقائية الجديدة في الإصدار 9.0 من المكوّن الإضافي Android Gradle.

التوافق

الحدّ الأقصى لمستوى واجهة برمجة تطبيقات Android الذي يتوافق معه الإصدار 9.0.0-beta04 من المكوّن الإضافي لنظام Gradle المتوافق مع Android هو المستوى 36 لواجهة برمجة التطبيقات.

يتطلّب الإصدار 9.0.0-beta04 من المكوّن الإضافي لنظام Gradle المتوافق مع Android استخدام الإصدار 9.0.0 من Gradle.

تنفّذ فئات android DSL الآن الواجهات العامة الجديدة فقط

على مدار السنوات العديدة الماضية، طرحنا واجهات جديدة للغة DSL وواجهة برمجة التطبيقات من أجل التحكّم بشكل أفضل في واجهات برمجة التطبيقات المتاحة للجميع. كانت إصدارات AGP‏ 7.x و8.x لا تزال تستخدم أنواع DSL القديمة (مثل BaseExtension) التي كانت تنفّذ أيضًا الواجهات العامة الجديدة، وذلك للحفاظ على التوافق أثناء تقدّم العمل على الواجهات.

يستخدم الإصدار 9.0 من AGP واجهات DSL الجديدة حصريًا، وتم تغيير عمليات التنفيذ إلى أنواع جديدة مخفية بالكامل. يؤدي ذلك أيضًا إلى إزالة إذن الوصول إلى واجهة برمجة التطبيقات القديمة والمتوقّفة نهائيًا الخاصة ببيانات المنتج المتغيرة.

لتحديث إصدار "استوديو Android" إلى 9.0، قد تحتاج إلى إجراء ما يلي:

• تأكَّد من أنّ مشروعك متوافق مع Kotlin المضمّن: لا يتوافق المكوّن الإضافي org.jetbrains.kotlin.android مع DSL الجديد.

• تبديل مشاريع KMP إلى المكوّن الإضافي لمكتبة Android Gradle المتوافق مع KMP: لا يتوافق استخدام المكوّن الإضافي org.jetbrains.kotlin.multiplatform في المشروع الفرعي نفسه لنظام Gradle مع المكوّنين الإضافيين com.android.library وcom.android.application مع نظام DSL الجديد.

• تعديل ملفات الإصدار: على الرغم من أنّ الهدف من تغيير الواجهات هو الحفاظ على تشابه لغة DSL قدر الإمكان، قد تحدث بعض التغييرات الصغيرة.

• تعديل منطق الإصدار المخصّص للإشارة إلى نظام DSL وواجهة برمجة التطبيقات الجديدَين: استبدِل أي إشارات إلى نظام DSL الداخلي بواجهات نظام DSL العامة. في معظم الحالات، سيكون هذا الاستبدال واحدًا مقابل واحد. استبدِل أي استخدام لواجهة برمجة التطبيقات applicationVariants وواجهات برمجة التطبيقات المشابهة بواجهة برمجة التطبيقات الجديدة androidComponents. قد يكون ذلك أكثر تعقيدًا، لأنّ واجهة برمجة التطبيقات androidComponents مصمَّمة لتكون أكثر استقرارًا من أجل الحفاظ على توافق المكوّنات الإضافية لفترة أطول. يمكنك الاطّلاع على وصفات Gradle للحصول على أمثلة.

• تحديث المكوّنات الإضافية التابعة لجهات خارجية: قد تعتمد بعض المكوّنات الإضافية التابعة لجهات خارجية على واجهات أو واجهات برمجة تطبيقات لم يعُد يتم عرضها. انتقِل إلى إصدارات من هذه المكوّنات الإضافية متوافقة مع الإصدار 9.0 من "مكوّن Android الإضافي في Gradle".

يمنع التبديل إلى واجهات DSL الجديدة المكوّنات الإضافية وبرامج Gradle النصية للإنشاء من استخدام واجهات برمجة التطبيقات المتوقّفة نهائيًا، بما في ذلك:

androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}

androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }

إذا تم التحديث إلى الإصدار 9.0 من AGP وظهرت رسالة الخطأ التالية، يعني ذلك أنّ مشروعك لا يزال يشير إلى بعض الأنواع القديمة:

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

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

android.newDsl=false

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

خلال مرحلة الإصدار الأوّلي من الإصدار 9.0، سنتواصل مع مطوّري المكوّنات الإضافية لمساعدتهم في تكييف مكوّناتهم الإضافية وإصدارها لتكون متوافقة تمامًا مع الأوضاع الجديدة، وسنحسّن "مساعد ترقية" Android Gradle Plugin في "استوديو Android" لإرشادك خلال عملية نقل البيانات.

إذا تبيّن لك أنّ واجهة برمجة التطبيقات الجديدة DSL أو Variant API لا تتضمّن إمكانات أو ميزات، يُرجى تسجيل مشكلة في أقرب وقت ممكن.

ميزات Kotlin المضمَّنة

يوفّر الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android إمكانية استخدام لغة Kotlin المضمّنة ويفعّلها تلقائيًا. وهذا يعني أنّه لم يعُد عليك تطبيق المكوّن الإضافي org.jetbrains.kotlin.android (أو kotlin-android) في ملفات الإصدار لتجميع ملفات مصدر Kotlin. يؤدي ذلك إلى تبسيط عملية دمج Kotlin مع AGP وتجنُّب استخدام واجهات برمجة التطبيقات المتوقّفة نهائيًا وتحسين الأداء في بعض الحالات.

لذلك، عند ترقية مشروعك إلى الإصدار 9.0 من Android Gradle Plugin، عليك أيضًا نقل البيانات إلى Kotlin المضمّنة أو إيقافها.

يمكنك أيضًا إيقاف ميزة التوافق المضمّنة مع Kotlin بشكل انتقائي لمشاريع Gradle الفرعية التي لا تتضمّن مصادر Kotlin.

الاعتماد على المكوّن الإضافي لنظام Gradle المتوافق مع Kotlin في وقت التشغيل

لتوفير إمكانية استخدام Kotlin المضمّنة، يتضمّن الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android الآن تبعية وقت التشغيل على الإصدار 2.2.10 من المكوّن الإضافي لنظام Gradle المتوافق مع Kotlin (KGP). هذا يعني أنّه لن يكون عليك تحديد إصدار KGP، وإذا كنت تستخدم إصدارًا أقدم من 2.2.10، سيتم تلقائيًا ترقية إصدار KGP إلى 2.2.10. وبالمثل، إذا كنت تستخدم إصدارًا من KSP أقل من 2.2.10-2.0.2، سيتم ترقيته إلى 2.2.10-2.0.2 ليتوافق مع إصدار KGP.

الترقية إلى إصدار أعلى من KGP

لاستخدام إصدار أحدث من KGP أو KSP، أضِف ما يلي إلى ملف الإنشاء ذي المستوى الأعلى:

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:KGP_VERSION")

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin:KSP_VERSION")
    }
}

الرجوع إلى إصدار KGP أقدم

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

لاستخدام إصدار أقل من KGP أو KSP، عليك تعريف هذا الإصدار في ملف الإصدار ذي المستوى الأعلى باستخدام تعريف إصدار دقيق:

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

يُرجى العِلم أنّ الحدّ الأدنى لإصدار KGP الذي يمكنك الرجوع إليه هو 2.0.0.

توافق بيئة التطوير المتكاملة مع عناصر الاختبار الثابتة

يتيح الإصدار 9.0 من "مكوّن Android الإضافي لنظام Gradle" استخدام أدوات الاختبار في بيئة التطوير المتكاملة (IDE) في "استوديو Android".

المكوّن الإضافي "المكتبة المدمجة"

يتيح لك Fused Library Plugin (إصدار تجريبي) نشر مكتبات متعددة كملف Android Library AAR واحد. ويمكن أن يسهّل ذلك على المستخدمين الاعتماد على العناصر المنشورة.

للحصول على معلومات حول كيفية البدء، يُرجى الاطّلاع على نشر عدّة مكتبات Android كحزمة واحدة باستخدام Fused Library.

تغييرات السلوك

يتضمّن الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android السلوكيات الجديدة التالية:

يتضمّن الإصدار 9.0 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" تعديلات على الإعدادات التلقائية لخصائص Gradle التالية. يمنحك ذلك خيار الحفاظ على سلوك الإصدار 8.13 من AGP عند الترقية:

android {
  defaultConfig {
    testInstrumentationRunner = "..."
  }
}

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

الميزات التي تمت إزالتها

يزيل الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android الوظائف التالية:

• إيقاف إمكانية تضمين تطبيقات Wear OS
  يزيل الإصدار 9.0 من "مكوّن Android الإضافي لبرنامج Gradle" إمكانية تضمين تطبيقات Wear OS، والتي لم تعُد متاحة في Play. ويشمل ذلك إزالة إعدادات wearApp وAndroidSourceSet.wearAppConfigurationName DSL. اطّلِع على مقالة التوزيع على Wear OS لمعرفة كيفية نشر تطبيقك على Wear OS.
• مهمة الإبلاغ عن androidDependencies وsourceSets
• إيقاف إتاحة حِزم APK المجزّأة حسب كثافة الشاشة
  في الإصدار 9.0 من "مكوّن Android الإضافي في Gradle"، تم إيقاف إمكانية إنشاء حِزم APK مجزّأة استنادًا إلى كثافة الشاشة. تمت إزالة الوظيفة وواجهات برمجة التطبيقات ذات الصلة. لتقسيم حِزم APK استنادًا إلى كثافة الشاشة باستخدام الإصدار 9.0 أو إصدار أحدث من "مكوّن Android الإضافي في Gradle"، استخدِم حِزم التطبيقات.

تغيير DSL

يتضمّن الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android تغييرات غير متوافقة في DSL على النحو التالي:

• تمت إزالة تحديد المَعلمات الخاص بـ CommonExtension.

  في حد ذاته، هذا التغيير هو تغيير غير متوافق على مستوى المصدر فقط للمساعدة في تجنُّب التغييرات غير المتوافقة المستقبلية على مستوى المصدر، ولكنّه يعني أيضًا أنّه يجب نقل طرق الحظر من CommonExtension إلى ApplicationExtension وLibraryExtension وDynamicFeatureExtension وTestExtension.

  عند ترقية مشروعك إلى الإصدار 9.0 من Android Gradle Plugin، عليك إعادة تصميم رمز المكوّن الإضافي Gradle الذي يستخدم هذه المَعلمات أو طرق الحظر. على سبيل المثال، تم تعديل المكوّن الإضافي التالي لإزالة المَعلمة "النوع" وعدم الاعتماد على طرق الحظر التي تمت إزالتها:

  AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  بالنسبة إلى المكوّنات الإضافية التي تستهدف نطاقًا من إصدارات "المكوّن الإضافي لنظام Android Gradle"، يكون استخدام الدالة getter مباشرةً متوافقًا مع إصدارات "المكوّن الإضافي لنظام Android Gradle" الأقل من 9.0.

تمت إزالة DSL

يزيل الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android ما يلي:

• AndroidSourceSet.jni، لأنّها لم تكن تعمل.

• AndroidSourceSet.wearAppConfigurationName، في ما يتعلق بإيقاف ميزة التطبيقات المضمّنة على Wear OS.

• BuildType.isRenderscriptDebuggable، لأنّها لم تكن تعمل.

• DependencyVariantSelection. تم استبداله بـ DependencySelection، والذي يتم عرضه على نحو kotlin.android.localDependencySelection

• Installation.installOptions(String). تم استبداله بالسمة القابلة للتعديل Installation.installOptions.

• الكتلة التجريبية PostProcessing التي لم يتم تثبيتها أبدًا

• ProductFlavor.setDimension، والتي تم استبدالها بالسمة dimension

• LanguageSplitOptions، الذي كان مفيدًا فقط في تطبيقات Google Play الفورية، والتي تم إيقافها نهائيًا.

• DensitySplit، لأنّ هذه الميزة لم تعُد متاحة. والبديل هو استخدام حِزم التطبيقات.

واجهات برمجة التطبيقات التي تمت إزالتها

يزيل الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android ما يلي:

• AndroidComponentsExtension.finalizeDSl. تم استبداله بـ finalizeDsl

• Component.transformClassesWith. تم استبداله بـ Instrumentation.transformClassesWith

• Component.setAsmFramesComputationMode. تم استبداله بـ Instrumentation.setAsmFramesComputationMode

• ComponentBuilder.enabled. تم استبداله بـ ComponentBuilder.enable.

• DependenciesInfoBuilder.includedInApk. تم استبداله بـ includeInApk

• DependenciesInfoBuilder.includedInBundle. تم استبداله بـ includeInBundle

• GeneratesApk.targetSdkVersion. تم استبداله بـ targetSdk

• Variant.minSdkVersion. تم استبداله بـ minSdk

• Variant.maxSdkVersion. تم استبداله بـ maxSdk

• Variant.targetSdkVersion. تم استبداله بـ targetSdk

• Variant.unitTest، لأنّها لم تكن تنطبق على المكوّن الإضافي com.android.test. يتوفّر النوع unitTest على الأنواع الفرعية VariantBuilder التي تتضمّن HasUnitTest.

• VariantBuilder.targetSdk وtargetSdkPreview، لأنّها لم تكن ذات معنى في المكتبات. يُرجى استخدام GeneratesApkBuilder.targetSdk أو GeneratesApkBuilder.targetSdkPreview بدلاً من ذلك.

• VariantBuilder.enableUnitTest، لأنّها لم تكن تنطبق على المكوّن الإضافي com.android.test. يتوفّر النوع enableUnitTest على الأنواع الفرعية VariantBuilder التي تتضمّن HasUnitTestBuilder.

• تمت إزالة VariantBuilder.unitTestEnabled واستبداله بـ enableUnitTest الذي يحمل اسمًا أكثر اتساقًا، وذلك في الأنواع الفرعية VariantBuilder التي تتضمّن HasUnitTestBuilder.

• VariantOutput.enable. تم استبداله بـ enabled

• تم إيقاف ميزتَي FeaturePlugin وFeatureExtension نهائيًا.

• واجهات برمجة التطبيقات BaseExtension.registerTransform التي تم إيقافها أو إزالتها نهائيًا، والتي كانت متاحة فقط للسماح بالتجميع باستخدام أحدث إصدار من "مكوّن Android الإضافي" مع استهداف الإصدار 4.2 أو الإصدارات الأقدم من "مكوّن Android الإضافي"

إزالة خصائص Gradle

تمت إضافة خصائص Gradle التالية في البداية كطرق لإيقاف الميزات المفعَّلة تلقائيًا على مستوى العالم.

تم إيقاف هذه الميزات تلقائيًا منذ الإصدار 8.0 أو الإصدارات الأقدم من "مكوّن Android الإضافي". فعِّل هذه الميزات في المشاريع الفرعية التي تستخدمها فقط للحصول على عملية إنشاء أكثر كفاءة.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

خصائص Gradle الإلزامية

يُصدر الإصدار 9.0 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" خطأً إذا ضبطت خصائص Gradle التالية.

لن يرقّي مساعد ترقية المكوّن الإضافي لنظام Gradle المتوافق مع Android المشاريع إلى الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android التي تستخدم هذه الخصائص.

المشاكل التي تم إصلاحها

الإصدار 9.0.0-beta04 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-beta03 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-beta02 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-beta01 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha14 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha13 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha12 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha11 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha10 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha09 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha08 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha07 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha06 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha05 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha04 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha03 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha02 من المكوّن الإضافي لنظام Gradle المتوافق مع Android

الإصدار 9.0.0-alpha01 من المكوّن الإضافي لنظام Gradle المتوافق مع Android