أضاف الإصدار 4.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android إمكانية استخدام لغة Kotlin في إعدادات عملية الإنشاء في Gradle كبديل لـ Groovy، وهي لغة البرمجة التي كانت تُستخدَم تقليديًا في ملفات إعدادات Gradle.
يُفضل استخدام Kotlin على لغة البرمجة Groovy في كتابة نصوص Gradle لأن لغة Kotlin أكثر قابلية للقراءة وتوفر دعمًا أفضل لوقت التجميع ودعم IDE.
على الرغم من أنّ 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. تأكد من استمرار تجميع مشروعك
بعد ترحيل كل ملف إصدار.
نقل أصغر الملفات أولاً، والحصول على خبرة، ثم الانتقال إلى الملفات الأكبر يمكنك الحصول على مزيج من ملفات تصميم 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 إلى كتلة المكوّنات الإضافية
إذا كان الإصدار يستخدم العنصر
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 الإضافي ومستودع 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.