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

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

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

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

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

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

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

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

العبارات الشائعة

‫Kotlin DSL: يشير هذا المصطلح في المقام الأول إلى المكوّن الإضافي لنظام Gradle المتوافق مع Android في 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 تضمين التعبيرات المنقّطة بين أقواس معقوفة. على سبيل المثال، في 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، عليك تغيير أسماء السمات إلى الطرق المستنتَجة غير المتوافقة مع 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") {
    ...
 }
}

Migrate from buildscript to plugins block

إذا كان الإصدار يستخدم مجموعة 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

يمكنك العثور على قائمة المكوّنات الإضافية الكاملة في مستودع Maven من Google.

يمكن الإشارة إلى مكوّنات 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 المركزي ومستودع Maven من Google. يمكنك قراءة تطوير مكوّنات 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 إلى السمات المنطقية

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

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

Migrate from buildscript to plugins block

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

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

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

متنوعة

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

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

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

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

إضافة "`=`" إلى مكالمات التعيين

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

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