تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

نقل إعدادات تصميمك من 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: يشير هذا المصطلح في المقام الأول إلى 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. تأكَّد من أنّه لا يزال بإمكانك compiling مشروعك بعد نقل كل ملف إنشاء.

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

إذا كان تصميمك يستخدم كتلة 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 Plugin Portal، Maven Central Repository وGoogle Maven repository. اقرأ تطوير مكوّنات Gradle المخصّصة لمزيد من المعلومات عن آلية عمل معرّفات المكوّنات الإضافية.

تنفيذ عملية إعادة التنظيم

بعد معرفة أرقام تعريف الإضافات التي تستخدمها، اتّبِع الخطوات التالية:

إذا كانت لديك مستودعات للمكونات الإضافية التي تمّ الإعلان عنها في القسم buildscript {} ، يمكنك نقلها إلى ملف settings.gradle بدلاً من ذلك.
أضِف المكوّنات الإضافية إلى العنصر plugins {} في ملف المستوى الأعلى build.gradle. تحتاج إلى تحديد المعرف وإصدار المكون الإضافي هنا. إذا لم تكن هناك حاجة إلى تطبيق المكوّن الإضافي على المشروع الجذر، استخدِم apply false.
أزِل الإدخالات classpath من ملف build.gradle.kts ذي المستوى الأعلى.
طبِّق المكوّنات الإضافية من خلال إضافتها إلى كتلة plugins {} في ملف build.gradle على مستوى الوحدة. ما عليك سوى تحديد رقم تعريف المكوّن الإضافي هنا لأنّ الإصدار يتم اكتسابه من المشروع الجذر.
أزِل طلب 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.