نقل إعدادات تصميمك من Groovy إلى Kotlin

أضاف الإصدار 4.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android إمكانية استخدام لغة Kotlin في إعدادات عملية الإنشاء في Gradle بدلاً من Groovy، وهي لغة البرمجة التي كانت تُستخدَم تقليديًا في ملفات إعدادات Gradle.

يُفضَّل استخدام لغة Kotlin على Groovy لكتابة نصوص Gradle لأنّ لغة Kotlin أكثر سهولة في القراءة، كما أنّها توفّر فحصًا أفضل في وقت الترجمة ودعمًا أفضل لبيئة تطوير البرامج المتكاملة.

على الرغم من أنّ Kotlin يوفّر حاليًا عملية دمج أفضل في محرِّر ملفّات الرمز البرمجي في Android Studio مقارنةً بـ Groovy، إلا أنّ عمليات الإنشاء التي تستخدم Kotlin تكون عادةً أبطأ من عمليات الإنشاء التي تستخدم Groovy، لذا ننصحك بالتفكير في أداء عملية الإنشاء عند اتخاذ قرار بشأن نقل البيانات.

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

المخطط الزمني

بدءًا من الإصدار Giraffe من "استوديو Android"، تستخدم المشاريع الجديدة لغة Kotlin DSL (build.gradle.kts) بشكل تلقائي لإعداد عملية التصميم. يوفّر ذلك تجربة تعديل أفضل مقارنةً بـ Groovy DSL (build.gradle) من خلال تمييز نحو الرموز البرمجية وإكمالها والتنقّل إلى التعريفات. لمزيد من المعلومات، اطّلِع على دليل Gradle Kotlin DSL.

المصطلحات الشائعة

Kotlin DSL: يشير هذا المصطلح في المقام الأول إلى Kotlin DSL لمكوّن Android Gradle الإضافي أو، في بعض الأحيان، إلى Kotlin DSL الأساسي في Gradle.

في دليل نقل البيانات هذا، يتم استخدام "Kotlin" و "Kotlin DSL" بالتبادل. وبالمثل، يتم استخدام Groovy وGroovy DSL بالتبادل.

تسمية ملفات النصوص البرمجية

تستند أسماء امتدادات ملفات النصوص البرمجية إلى اللغة التي تمت كتابة ملف الإنشاء بها:

• تستخدم ملفات إنشاء Gradle المكتوبة بلغة Groovy امتداد اسم الملف .gradle.
• تستخدم ملفات إنشاء Gradle المكتوبة بلغة Kotlin إضافة اسم الملف.gradle.kts.

تحويل البنية

هناك بعض الاختلافات العامة في البنية بين Groovy وKotlin، لذلك عليك تطبيق هذه التغييرات في نصوص إنشاء البرامج.

إضافة قوسَين إلى طلبات تنفيذ الطريقة

تتيح لك Groovy حذف الأقواس في استدعاءات الطرق، في حين تتطلّب Kotlin استخدامها. لنقل الإعدادات، أضِف قوسَين إلى هذه الأنواع من طلبات الاستدعاء. توضِّح هذه التعليمة البرمجية كيفية ضبط إعداد في Groovy:

compileSdkVersion 30

في ما يلي الرمز البرمجي نفسه مكتوبًا بلغة Kotlin:

compileSdkVersion(30)

إضافة = إلى مكالمات المهام

يتيح لك أسلوب Groovy DSL حذف عامل الربط = عند تعيين السمات، في حين تتطلّب Kotlin استخدامه. يوضّح هذا الرمز كيفية تخصيص السمات في Groovy:

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

توضِّح هذه الرموز البرمجية كيفية منح سمات في Kotlin:

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

تحويل السلاسل

في ما يلي الاختلافات في السلاسل بين Groovy وKotlin:

• علامات الاقتباس المزدوجة للسلاسل: على الرغم من أنّ Groovy يسمح بتحديد السلاسل باستخدام علامات الاقتباس المفردة، يتطلّب Kotlin استخدام علامات الاقتباس المزدوجة.

• إدراج سلاسل في التعبيرات التي تحتوي على نقاط: في Groovy، يمكنك استخدام البادئة $ فقط ل إدراج سلاسل في التعبيرات التي تحتوي على نقاط، ولكن تتطلّب Kotlin إحاطة التعبيرات التي تحتوي على نقاط بقوسين معقوفين. على سبيل المثال، في Groovy، يمكنك استخدام $project.rootDir كما هو موضّح في المقتطف التالي:

      myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
      

  في لغة Kotlin، يُطلِق الرمز السابق toString() على project، وليس على project.rootDir. للحصول على قيمة directory الجذر، عليك إحاطة تعبير ${project.rootDir} بالقوسين المتعرجَين:

      myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
      

  لمزيد من المعلومات، اطّلِع على نماذج السلاسل في مستندات Kotlin.

إعادة تسمية امتدادات الملفات

يمكنك إلحاق .kts بكل ملف إنشاء أثناء نقل محتوياته. على سبيل المثال، اختَر ملف إنشاء، مثل ملف settings.gradle. أعِد تسمية الملف إلى settings.gradle.kts وحوِّل محتوى الملف إلى Kotlin. تأكَّد من أنّه لا يزال بإمكانك compiling مشروعك بعد نقل كل ملف إنشاء.

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

استبدِل def بـ val أو var

استبدِل def بـ val أو var، وهو الطريقة التي تحدِّد بها المتغيّرات في Kotlin. في ما يلي بيان متغيّر في Groovy:

def building64Bit = false

في ما يلي الرمز البرمجي نفسه مكتوبًا بلغة Kotlin:

val building64Bit = false

إضافة is كبادئة للسمات المنطقية

يستخدم Groovy منطق استنتاج السمات استنادًا إلى أسماء السمات. بالنسبة إلى السمة المنطقية foo، يمكن أن تكون الطرق المستنتجة getFoo أو setFoo أو isFoo. وبالتالي، بعد التحويل إلى Kotlin، عليك تغيير أسماء السمات إلى الطرق المستنتجة التي لا تتوافق مع Kotlin. على سبيل المثال، بالنسبة إلى buildTypes عناصر DSL المنطقية، عليك إضافة البادئة is إليها. يوضّح هذا الرمز المبرمَج كيفية ضبط السمات المنطقية في Groovy:

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            ...
        }
        debug {
            debuggable true
            ...
        }
    ...

في ما يلي الرمز نفسه في Kotlin. يُرجى العِلم أنّه تتم إضافة البادئة is إلى المواقع.

android {
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            isShrinkResources = true
            ...
        }
        getByName("debug") {
            isDebuggable = true
            ...
        }
    ...

تحويل القوائم والخرائط

يتم تحديد القوائم والخرائط في Groovy وKotlin باستخدام بنية مختلفة. تستخدم Groovy []، في حين تستدعي Kotlin طرق إنشاء المجموعة بشكل صريح باستخدام listOf أو mapOf. احرص على استبدال [] بـ listOf أو mapOf عند نقل البيانات.

في ما يلي كيفية تعريف قائمة في Groovy مقارنةً بـ Kotlin:

jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]

في ما يلي الرمز البرمجي نفسه مكتوبًا بلغة Kotlin:

jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")

في ما يلي كيفية تعريف خريطة في Groovy مقارنةً بـ Kotlin:

def myMap = [key1: 'value1', key2: 'value2']

في ما يلي الرمز البرمجي نفسه مكتوبًا بلغة Kotlin:

val myMap = mapOf("key1" to "value1", "key2" to "value2")

ضبط أنواع الإصدار

في Kotlin DSL، لا يتوفّر سوى نوعَي الإصدار وإصدار تصحيح الأخطاء بشكل ضمني. يجب إنشاء جميع أنواع التصاميم المخصّصة الأخرى يدويًا.

في Groovy، يمكنك استخدام أنواع الإصدارات المخصّصة لتصحيح الأخطاء والإصدارات العادية وأنواع أخرى معيّنة من الإصدارات بدون إنشائها أولاً. يعرض مقتطف الرمز التالي إعدادًا يتضمّن نوعَي الإنشاء debug وrelease و benchmark في Groovy.

buildTypes {
 debug {
   ...
 }
 release {
   ...
 }
 benchmark {
   ...
 }
}

لإنشاء الإعدادات المكافئة في Kotlin، عليك إنشاء نوع الإنشاء benchmark بشكل صريح.

buildTypes {
 debug {
   ...
 }

 release {
   ...
 }
 register("benchmark") {
    ...
 }
}

نقل البيانات من buildscript إلى كتلة plugins

إذا كان الإصدار يستخدم العنصر buildscript {} لإضافة مكوّنات إضافية إلى المشروع، عليك إعادة صياغة الإصدار لاستخدام العنصر plugins {} بدلاً من ذلك. يسهّل الرمز البرمجي plugins {} تطبيق المكوّنات الإضافية، وهو يعمل بشكل جيد مع قوائم الإصدارات.

بالإضافة إلى ذلك، عند استخدام العنصر plugins {} في ملفات الإنشاء، يكون "استوديو Android" على دراية بالسياق حتى في حال تعذّر الإنشاء. يساعد هذا السياق في إجراء إصلاحات على ملفات Kotlin DSL لأنّه يسمح لـ Studio IDE بتنفيذ إكمال الرموز البرمجية وتقديم اقتراحات مفيدة أخرى.

العثور على أرقام تعريف المكوّنات الإضافية

في حين أنّ العنصر buildscript {} يضيف المكوّنات الإضافية إلى مسار فئة البناء باستخدام إحداثيات Maven للمكوّن الإضافي، على سبيل المثال com.android.tools.build:gradle:7.4.0، يستخدم العنصر plugins {} أرقام تعريف المكوّنات الإضافية بدلاً من ذلك.

بالنسبة إلى معظم المكوّنات الإضافية، يكون رقم تعريف المكوّن الإضافي هو السلسلة المستخدَمة عند تطبيقها باستخدام apply plugin. على سبيل المثال، أرقام تعريف المكوّنات الإضافية التالية هي جزء من المكوّن الإضافي لنظام Gradle المتوافق مع Android:

• com.android.application
• com.android.library
• com.android.lint
• com.android.test

يمكنك العثور على قائمة المكوّنات الإضافية الكاملة في مستودع Google Maven.

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

أرقام تعريف المكوّنات الإضافية المختصرة	أرقام تعريف المكوّنات الإضافية المستندة إلى مساحة الاسم
kotlin	org.jetbrains.kotlin.jvm
kotlin-android	org.jetbrains.kotlin.android
kotlin-kapt	org.jetbrains.kotlin.kapt
kotlin-parcelize	org.jetbrains.kotlin.plugin.parcelize

يمكنك أيضًا البحث عن المكوّنات الإضافية على Gradle Plugin Portal، Maven Central Repository وGoogle Maven repository. اطّلِع على مقالة إنشاء مكوّنات إضافية مخصّصة لنظام Gradle لمعرفة مزيد من المعلومات عن آلية عمل أرقام تعريف المكوّنات الإضافية.

تنفيذ عملية إعادة التنظيم

بعد معرفة أرقام تعريف الإضافات التي تستخدمها، اتّبِع الخطوات التالية:

1. إذا كانت لديك مستودعات للمكونات الإضافية التي تمّ الإعلان عنها في القسم buildscript {} ، يمكنك نقلها إلى ملف settings.gradle بدلاً من ذلك.

2. أضِف المكوّنات الإضافية إلى العنصر plugins {} في ملف المستوى الأعلى build.gradle. عليك تحديد رقم التعريف و الإصدار من المكوّن الإضافي هنا. إذا لم يكن المكوّن الإضافي بحاجة إلى تطبيقه على المشروع الجذر، استخدِم apply false.

3. أزِل إدخالات classpath من ملف build.gradle.kts على المستوى الأعلى.

4. طبِّق المكوّنات الإضافية من خلال إضافتها إلى العنصر plugins {} فيملفbuild.gradle على مستوى الوحدة. ما عليك سوى تحديد رقم تعريف المكوّن الإضافي هنا لأنّ الإصدار يتم اكتسابه من المشروع الجذر.

5. أزِل طلب apply plugin للإضافة من ملف build.gradle على مستوى الوحدة.

على سبيل المثال، يستخدم هذا الإعداد العنصر buildscript {}:

// Top-level build.gradle file
buildscript {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:7.4.0")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0")
        ...
    }
}

// Module-level build.gradle file
apply(plugin: "com.android.application")
apply(plugin: "kotlin-android")

في ما يلي إعداد مماثل باستخدام العنصر plugins {}:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.4.0' apply false
   id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   id 'org.jetbrains.kotlin.android'
   ...
}

// settings.gradle
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

تحويل مجموعة المكوّنات الإضافية

يتشابه تطبيق المكوّنات الإضافية من العنصر plugins {} في Groovy وKotlin. يوضّح الرمز التالي كيفية تطبيق المكوّنات الإضافية في Groovy عند استخدام قوائم الإصدارات:

// Top-level build.gradle file
plugins {
   alias libs.plugins.android.application apply false
   ...
}

// Module-level build.gradle file
plugins {
   alias libs.plugins.android.application
   ...
}

توضِّح التعليمة البرمجية التالية كيفية إجراء ذلك في Kotlin:

// Top-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application) apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application)
   ...
}

يوضِّح الرمز التالي كيفية تطبيق المكوّنات الإضافية في Groovy عندما لا تستخدم كتالوجات الإصدارات:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.3.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   ...
}

توضِّح التعليمة البرمجية التالية كيفية إجراء ذلك في Kotlin:

// Top-level build.gradle.kts file
plugins {
   id("com.android.application") version "7.3.0" apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   id("com.android.application")
   ...
}

لمزيد من التفاصيل حول العنصر plugins {}، يُرجى الاطّلاع على تطبيق المكوّنات الإضافية في مستندات Gradle.

متنوعة

للحصول على نماذج رمز Kotlin لوظائف أخرى، يمكنك الاطّلاع على صفحات مستندات التالية:

• إذا كانت لديك إعدادات ProGuard، يُرجى الرجوع إلى مقالة تفعيل التقليل والتشويه والتحسين.
• إذا كان لديك رمز signingConfig {}، راجِع مقالة إزالة معلومات التوقيع من ملفات الإنشاء.
• إذا كنت تستخدم مواقع على مستوى المشروع، راجِع مقالة ضبط المواقع على مستوى المشروع.

المشاكل المعروفة

في الوقت الحالي، مشكلة معروفة هي أنّ سرعة الإنشاء قد تكون أبطأ باستخدام Kotlin مقارنةً باستخدام Groovy.

كيفية الإبلاغ عن المشاكل

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

مزيد من المراجع

للحصول على مثال عملي على ملفات إنشاء Gradle المكتوبة باستخدام Kotlin، يُرجى الاطّلاع على تطبيق Now In Android النموذجي على GitHub.