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

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

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

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

على الرغم من أنّ Kotlin توفّر حاليًا تكاملاً أفضل في محرّر الرموز البرمجية في "استوديو Android" مقارنةً بلغة 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. على سبيل المثال، بالنسبة إلى عناصر قيمة منطقية في لغة DSL buildTypes، عليك إضافة البادئة 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 باستخدام أرقام تعريف إضافات متعددة. ننصحك باستخدام معرّف الإضافة ذي مساحة الاسم، وإعادة تصميم الرمز من معرّف الإضافة المختصر إلى معرّف الإضافة ذي مساحة الاسم باستخدام الجدول التالي:

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

تنفيذ إعادة البناء

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

إذا كان لا يزال لديك مستودعات للمكوّنات الإضافية تم تحديدها في الحظر 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.

نقل إعدادات تصميمك من Groovy إلى Kotlin تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

تسمية ملفات النصوص البرمجية

تحويل البنية

إضافة أقواس إلى استدعاءات الدوال

إضافة = إلى مكالمات الواجب

تحويل السلاسل

إعادة تسمية امتدادات الملفات

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

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

تحويل القوائم والخرائط

ضبط أنواع الإصدارات

نقل البيانات من buildscript إلى قسم الإضافات

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

تنفيذ إعادة البناء

تحويل مربّع المكوّنات الإضافية

بنود متنوعة

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

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

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

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

إضافة `=` إلى مكالمات الواجب

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

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