دليل نقل البيانات في حزمة تطوير البرامج (SDK) 3.0 لتطبيقات Android المخصّصة للمستهلكين

نقل البيانات إلى Kotlin 2.0

إذا كنت تستخدم حزمة تطوير البرامج (SDK) للمستهلك لنظام التشغيل Android 3.0 أو إصدار أحدث، عليك الترقية إلى Kotlin 2.0. تقدّم هذه الصفحة إرشادات لتسهيل عملية الانتقال إلى إصدار Kotlin الجديد.

توافق Gradle وAGP

يتضمّن الإصدار 2.0 من Kotlin متطلبات للحد الأدنى والحد الأقصى للإصدارات من Gradle والمكوّن الإضافي لنظام Gradle المتوافق مع Android ‏ (AGP). تأكَّد من أنّ مشروعك يستوفي هذه المتطلبات لإصدار Kotlin 2.0.

الحد الأدنى لإصدار AGP للإصدار 3.0 من حزمة تطوير البرامج (SDK) للمستهلك أو الإصدارات الأحدث

يتطلّب الإصدار 3.0 من حزمة تطوير البرامج (SDK) للمستهلك استخدام الإصدار 7.3 من المكوّن الإضافي لنظام Gradle المتوافق مع Android أو إصدار أحدث.

الوضع الكامل لأداة R8

لا يتوافق الإصدار 3 من حزمة تطوير البرامج (SDK) للمستهلك والإصدارات الأقدم مع وضع R8 الكامل. يجب إيقاف وضع R8 الكامل صراحةً إذا كان تطبيقك يستهدف الإصدار 8.0 من "مكوّن Gradle الإضافي لنظام Android" أو الإصدارات الأحدث.

# settings.gradle
android.enableR8.fullMode=false

التوافق مع إصدارات Kotlin

تتيح لغة Kotlin التوافق مع الأنظمة القديمة من خلال ثلاثة إصدارات سابقة من اللغة. هذا يعني أنّه إذا كنت تستخدم حاليًا الإصدار 1.7 من Kotlin أو إصدارًا أحدث مع حزمة تطوير البرامج (SDK) للمستهلك، من المفترض أن تتمكّن من الترقية إلى الإصدار 2.0 من Kotlin بدون الحاجة إلى حلّ جميع التغييرات التي قد تؤدي إلى عطل. ومع ذلك، لا ينطبق توافق Kotlin إلا على ميزات اللغة الثابتة. إذا كنت تستخدم ميزات أولية أو تجريبية في لغة Kotlin، قد تحتاج إلى إجراء تغييرات إضافية عند الترقية.

علامات التوافق مع Kotlin

كما هو موضّح في القسم السابق، تتوافق Kotlin مع ما يصل إلى 3 إصدارات سابقة من اللغة عند الترقية. توفّر لغة Kotlin علامتَين للمساعدة في الحدّ من التغييرات التي قد تؤدي إلى عطل:

language-version X.Y

تؤدي هذه العلامة إلى التراجع عن التغييرات التي قد تؤدي إلى عطل في سلوك إصدار Kotlin السابق. على سبيل المثال، إذا كنت تستخدم الإصدار 1.7 من Kotlin، يمكنك تحديد [ - language-version 1.7] ولن تسري التغييرات الجديدة التي قد تؤدي إلى عطل:

android {
   kotlinOptions {
       languageVersion = '1.7'
   }
}
api-version X.Y

تمنع هذه العلامة استخدام واجهات برمجة التطبيقات الجديدة قبل أن يصبح الرمز البرمجي التابع جاهزًا لدمج Kotlin 2.0.

android {
   kotlinOptions {
       apiVersion = '1.7'
   }
}

نهج أكثر استهدافًا

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