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

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

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

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

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

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

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

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

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

      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 وGrofy في مشروع، لذا خصِّص الوقت الكافي لإجراء هذا الانتقال بعناية.

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

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

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

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

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

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

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

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

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