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

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

يُفضل استخدام Kotlin على لغة البرمجة Groovy في كتابة نصوص Gradle لأن لغة Kotlin أكثر قابلية للقراءة وتوفر دعمًا أفضل لوقت التجميع ودعم IDE.

على الرغم من أنّ 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. تأكد من استمرار تجميع مشروعك بعد ترحيل كل ملف إصدار.

نقل أصغر الملفات أولاً، والحصول على خبرة، ثم الانتقال إلى الملفات الأكبر يمكنك الحصول على مزيج من ملفات تصميم 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 إلى كتلة المكوّنات الإضافية

إذا كان الإصدار يستخدم العنصر 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 الإضافية من خلال معرّفات مكونات إضافية متعددة. ننصحك باستخدام معرّف المكوّن الإضافي الذي يتضمّن مساحة الاسم، وإعادة التنظيم من الاختصار إلى معرّف المكوّن الإضافي الذي يتضمّن مساحة الاسم وفقًا للجدول التالي:

أرقام تعريف مكوّنات Shorthand الإضافية أرقام تعريف المكوّنات الإضافية التي تتضمّن مساحة الاسم
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 الإضافي ومستودع Maven المركزي ومستودع Google Maven. اقرأ تطوير مكوّنات 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 لوظائف أخرى، يمكنك الاطّلاع على صفحات مستندات التالية:

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

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

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

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

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

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