نقل إعدادات تصميمك من 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: يشير في المقام الأول إلى مكوّن Android Gradle الإضافي المستند إلى Kotlin DSL أو، في بعض الأحيان، إلى مكوّن Gradle الإضافي الأساسي المستند إلى Kotlin DSL.

في دليل النقل هذا، يتم استخدام "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 تضمين التعبيرات المنقّطة بين أقواس معقوفة. على سبيل المثال، يمكنك استخدام $project.rootDir في Groovy كما هو موضّح في المقتطف التالي:

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

  في Kotlin، يستدعي الرمز السابق الدالة toString() على project، وليس على project.rootDir. للحصول على قيمة الدليل الجذر، ضَع التعبير ${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، لأنّه يتيح بيئة التطوير المتكاملة (IDE) في "استوديو Android" إكمال الرموز البرمجية وتقديم اقتراحات مفيدة أخرى.

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

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

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

• إذا كان لديك إعداد ProGuard، يُرجى الرجوع إلى مقالة تفعيل التصغير والتشويش والتحسين.
• إذا كان لديك حظر signingConfig {}، يُرجى الرجوع إلى إزالة معلومات التوقيع من ملفات الإصدار.
• في حال استخدام خصائص على مستوى المشروع، يُرجى الرجوع إلى إعداد خصائص على مستوى المشروع.

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

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

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

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

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

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