این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

پیکربندی ساخت خود را از Groovy به Kotlin منتقل کنید

افزونه Android Gradle 4.0 پشتیبانی از استفاده از Kotlin در پیکربندی ساخت Gradle را به عنوان جایگزینی برای Groovy، زبان برنامه نویسی که به طور سنتی در فایل های پیکربندی Gradle استفاده می شود، اضافه کرد.

Kotlin برای نوشتن اسکریپت های Gradle بر Groovy ترجیح داده می شود زیرا Kotlin خواناتر است و بررسی زمان کامپایل و پشتیبانی IDE بهتری را ارائه می دهد.

اگرچه Kotlin در حال حاضر در مقایسه با Groovy ادغام بهتری در ویرایشگر کد اندروید استودیو ارائه می‌دهد، ساخت‌های با استفاده از Kotlin نسبت به ساخت‌هایی که از Groovy استفاده می‌کنند کندتر هستند، بنابراین هنگام تصمیم‌گیری برای مهاجرت، عملکرد ساخت را در نظر بگیرید.

این صفحه اطلاعات اولیه در مورد تبدیل فایل های ساخت Gradle برنامه اندروید شما از Groovy به Kotlin را ارائه می دهد. برای راهنمای جامع تر مهاجرت، به اسناد رسمی Gradle مراجعه کنید.

جدول زمانی

با شروع Android Studio Giraffe، پروژه های جدید به طور پیش فرض از Kotlin DSL ( build.gradle.kts ) برای پیکربندی ساخت استفاده می کنند. این تجربه ویرایش بهتری نسبت به Groovy DSL ( build.gradle ) با برجسته‌سازی نحو، تکمیل کد و پیمایش به اعلان‌ها ارائه می‌دهد. برای کسب اطلاعات بیشتر، Gradle Kotlin DSL Primer را ببینید.

اصطلاحات رایج

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 نیاز دارد که عبارات نقطه‌دار را با پرانتزهای فرفری بپیچید. به عنوان مثال، در 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 از [] استفاده می کند، در حالی که کاتلین روش های ایجاد مجموعه را به صراحت با استفاده از 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 Studio حتی زمانی که ساختن با شکست مواجه می‌شود، از زمینه آگاه است. این زمینه به اصلاح فایل‌های 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 را می توان با چندین شناسه پلاگین ارجاع داد. توصیه می‌کنیم از شناسه افزونه namespaced استفاده کنید و شناسه افزونه با فاصله نام را با جدول زیر تغییر دهید:

شناسه های افزایه کوتاه	شناسه‌های افزونه با فضای نام
`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 سطح ماژول اعمال کنید. فقط باید شناسه افزونه را در اینجا مشخص کنید زیرا نسخه از پروژه root به ارث رسیده است.
فراخوانی 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 مراجعه کنید.

متفرقه

برای نمونه کد کاتلین برای سایر عملکردها، به صفحات مستندات زیر مراجعه کنید:

اگر پیکربندی ProGuard دارید، به Enable shrinking, obfuscation, and optimization مراجعه کنید.
اگر بلوک signingConfig {} دارید، به حذف اطلاعات امضا از فایل های ساخت خود مراجعه کنید.
اگر از ویژگی های گسترده پروژه استفاده می کنید، به پیکربندی ویژگی های گسترده پروژه مراجعه کنید.

مسائل شناخته شده

در حال حاضر، یک مسئله شناخته شده این است که سرعت ساخت ممکن است با Kotlin کمتر از Groovy باشد.

نحوه گزارش مشکلات

برای دستورالعمل‌هایی درباره نحوه ارائه اطلاعاتی که برای تریاژ مشکل شما نیاز داریم، به جزئیات مربوط به ابزارهای ساخت و اشکالات Gradle مراجعه کنید. سپس، با استفاده از ردیاب مشکل عمومی Google، یک اشکال را ثبت کنید.

منابع بیشتر

برای نمونه‌ای از فایل‌های ساخت Gradle که با Kotlin نوشته شده‌اند، به برنامه نمونه Now In Android در GitHub مراجعه کنید.

پیکربندی ساخت خود را از Groovy به Kotlin منتقل کنید

جدول زمانی

اصطلاحات رایج

نامگذاری فایل اسکریپت

سینتکس را تبدیل کنید

به فراخوانی های متد پرانتز اضافه کنید

افزودن = به تماس‌های اختصاصی

تبدیل رشته ها

تغییر نام پسوند فایل

def با val یا var جایگزین کنید

پیشوند خواص بولی با is

تبدیل لیست ها و نقشه ها

پیکربندی انواع ساخت

مهاجرت از buildscript به بلوک پلاگین

شناسه های افزونه را پیدا کنید

بازسازی مجدد را انجام دهید

بلوک پلاگین ها را تبدیل کنید

متفرقه

مسائل شناخته شده

نحوه گزارش مشکلات

منابع بیشتر

افزودن `=` به تماس‌های اختصاصی

`def` با `val` یا `var` جایگزین کنید

پیشوند خواص بولی با `is`