نقل إعدادات تصميمك من 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) مع ميزات تمييز بناء الجملة وإكمال الرمز البرمجي والتنقّل إلى التعريفات. لمزيد من المعلومات، اطّلِع على مقدمة حول لغة Kotlin الخاصة بنظام Gradle.

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

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