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

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

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

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

توفر هذه الصفحة معلومات أساسية حول تحويل عنوان URL الخاص بتطبيق Android إنشاء Gradle الملفات من 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 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 وGroovy في مشروع، لذا خذ وقتك الانتقال بعناية.

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

استبدِل def بـ val أو var، وهو كيفية تعريف المتغيرات في Kotlin. هذا تعريف متغير في Groovy:

def building64Bit = false

هذه هي نفس التعليمة البرمجية المكتوبة في Kotlin:

val building64Bit = false

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

يستخدم تطبيق Groovy منطق خصم المواقع بناءً على أسماء الخصائص. بالنسبة إلى السمة المنطقية foo، تكون الطرق المستخلصة منها يمكن أن يكون getFoo أو setFoo أو isFoo. وهكذا ذات مرة بالتحويل إلى لغة كوتلين، تحتاج إلى تغيير أسماء الخصائص إلى الطرق التي تم استنتاجها غير المتاحة في 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 الإضافية من خلال معرّفات مكونات إضافية متعددة. ننصح باستخدام معرِّف المكون الإضافي المحدد في مساحة الاسم، وإعادة البناء من الاختصار إلى معرِّف المكون الإضافي المُحدد مساحة الاسم من خلال الجدول التالي:

معرفات المكونات الإضافية المختصرة أرقام تعريف المكوّنات الإضافية التي تتضمّن مساحة الاسم
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.