به افزونه Android-KMP مهاجرت کنید

پیش از این، تنها راه برای ادغام اندروید در یک پروژه KMP، استفاده از پلاگین معمولی کتابخانه اندروید Gradle بود: com.android.library . با این حال، این رویکرد اکنون به نفع افزونه اختصاصی com.android.kotlin.multiplatform.library که به آن افزونه Android-KMP نیز می‌گویند، منسوخ شده است. این راهنما نحوه مهاجرت به افزونه جدید را توضیح می دهد.

ویژگی ها و تفاوت های کلیدی

افزونه Android-KMP ( com.android.kotlin.multiplatform.library ) به طور خاص برای پروژه های KMP طراحی شده است و از چندین جنبه کلیدی با افزونه سنتی com.android.library متفاوت است:

  • معماری تک گونه: این افزونه با یک نوع کار می کند و با حذف پشتیبانی از طعم محصول و انواع ساخت که معمولاً در پروژه های کتابخانه استاندارد اندروید یافت می شود، فرآیند ساخت را ساده می کند. این پیکربندی را ساده می‌کند و عملکرد ساخت کتابخانه‌های اندروید KMP را افزایش می‌دهد.
  • بهینه سازی شده برای KMP: این افزونه به طور خاص برای کتابخانه های چند پلتفرمی Kotlin طراحی شده است که بر روی کد مشترک Kotlin و قابلیت همکاری تمرکز دارد. در نتیجه، پشتیبانی از ساخت‌های بومی مخصوص اندروید، AIDL (زبان تعریف رابط اندروید) و RenderScript را که معمولاً در زمینه کد مشترک KMP مرتبط نیستند، حذف نمی‌کند.
  • تست‌ها به‌طور پیش‌فرض غیرفعال می‌شوند: برای افزایش بیشتر سرعت ساخت در یک محیط چندپلتفرمی، آزمایش‌ها به‌طور پیش‌فرض غیرفعال می‌شوند. در صورت نیاز برای پروژه خود می توانید به صراحت تست ها را فعال کنید. این هم برای تست هاست (تست های واحد) و هم برای تست های روی دستگاه (تست های ابزار دقیق) اعمال می شود.
  • بدون برنامه افزودنی اندروید سطح بالا: این افزونه یک پسوند android سطح بالا در فایل های ساخت Gradle شما ایجاد نمی کند. پیکربندی با یک بلوک androidLibrary در DSL چند پلتفرمی Kotlin انجام می شود و ساختار پروژه KMP یکنواخت را حفظ می کند.
  • کامپایل Java Opt-in: کامپایل جاوا به طور پیش فرض فعال نیست. اگر کتابخانه KMP شما نیاز به کامپایل کدهای مبتنی بر جاوا دارد، باید به صراحت با استفاده از API withJava() در بلوک پیکربندی androidLibrary در بلوک kotlin خود انتخاب کنید. این امکان کنترل دقیق‌تری بر فرآیند کامپایل را فراهم می‌کند و می‌تواند زمان‌های ساخت را در زمانی که کامپایل کد مبتنی بر جاوا مورد نیاز نیست، بهبود بخشد.

مزایای مهاجرت

افزونه Android-KMP مزایای زیر را برای پروژه های KMP فراهم می کند:

  • بهبود عملکرد و پایداری ساخت: افزونه Android-KMP برای سرعت ساخت بهینه و پایداری افزایش یافته در پروژه های KMP مهندسی شده است. معماری ساده و تمرکز بر گردش کار KMP به فرآیند ساخت کارآمدتر و قابل اعتمادتر کمک می کند.
  • یکپارچه سازی IDE پیشرفته: این افزونه یکپارچه سازی عالی با Android Studio و سایر IDE های Kotlin فراهم می کند. این منجر به تکمیل کد، پیمایش، اشکال‌زدایی و تجربه کلی توسعه‌دهنده هنگام کار با کتابخانه‌های اندروید KMP می‌شود.
  • پیکربندی پروژه ساده شده: افزونه Android-KMP با حذف پیچیدگی های خاص اندروید مانند انواع مختلف، پیکربندی پروژه های KMP را ساده می کند. این منجر به فایل‌های ساخت پاک‌تر و قابل نگهداری‌تر و کاهش منحنی یادگیری برای توسعه‌دهندگانی می‌شود که تازه به توسعه KMP Android می‌پردازند. پیش از این، هنگام ادغام Android در یک پروژه KMP با استفاده از افزونه com.android.library ، تعامل بین افزونه Android Gradle و پلاگین Kotlin Gradle در ساختار چند پلتفرمی گاهی منجر به نام‌های مجموعه منبع گمراه‌کننده می‌شد. به عنوان مثال، مجموعه منبع اختصاص داده شده به پیکربندی تست های دارای ابزار اندروید، androidAndroidTest نام داشت. این قرارداد نامگذاری برای توسعه دهندگانی که با ساختارهای استاندارد پروژه KMP آشنا بودند کمتر بصری بود.
  • راه حل رسمی و پیشنهادی: افزونه com.android.kotlin.multiplatform.library جایگزین رسمی روش قبلی برای افزودن اهداف Android به کتابخانه های KMP با استفاده از افزونه com.android.library است. ادامه استفاده از افزونه com.android.library برای KMP دیگر توسط JetBrains پشتیبانی نمی‌شود و از به‌روزرسانی‌ها و بهبودهای آینده بهره‌مند نخواهد شد.

افزونه Android-KMP را در یک پروژه اعمال کنید

دو راه اصلی برای اعمال افزونه Android-KMP در پروژه شما وجود دارد: * برای ماژول های کتابخانه KMP موجود، فایل های Gradle خود را به صورت دستی ویرایش کنید . * برای ماژول های جدید کتابخانه KMP، ماژول جدید را مستقیماً از رابط کاربری Android Studio ایجاد کنید .

افزونه را روی یک ماژول موجود اعمال کنید

برای اعمال افزونه Android-KMP در یک ماژول کتابخانه KMP موجود، این مراحل را دنبال کنید:

  1. فایل TOML کاتالوگ نسخه خود را باز کنید و موارد زیر را به بخش plugins اضافه کنید:

    [plugins]
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform",
version.ref = "KOTLIN_PLUGIN_VERSION" }
android-kotlin-multiplatform-library = { id =
"com.android.kotlin.multiplatform.library", version.ref =
"ANDROID_KMP_PLUGIN_VERSION" }

    KOTLIN_PLUGIN_VERSION و ANDROID_KMP_PLUGIN_VERSION با نسخه های واقعی که استفاده می کنید جایگزین کنید.

  2. فایل build.gradle.kts (Kotlin) یا build.gradle (Groovy) خود را در ریشه ماژول کتابخانه KMP خود باز کنید.

  3. افزونه را در بالای فایل خود در بلوک plugins اعمال کنید:

    کاتلین 

    plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library) apply false
}

    شیار 

    plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library) apply false
}

  4. بلوک چند پلتفرمی Kotlin ( kotlin ) را برای تعریف هدف اندروید پیکربندی کنید. در بلوک kotlin ، هدف Android را با استفاده از androidLibrary مشخص کنید:

    کاتلین 

    kotlin {
   androidLibrary {
       namespace = "com.example.kmpfirstlib"
       compileSdk = 33
       minSdk = 24

       withJava() // enable java compilation support
       withHostTestBuilder {}.configure {}
       withDeviceTestBuilder {
           sourceSetTreeName = "test"
       }

       compilations.configureEach {
           compilerOptions.configure {
               jvmTarget.set(
                   org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
               )
           }
       }
   }

   sourceSets {
       androidMain {
           dependencies {
               // Add Android-specific dependencies here
           }
       }
       getByName("androidHostTest") {
           dependencies {
           }
       }

       getByName("androidDeviceTest") {
           dependencies {
           }
       }
   }
   // ... other targets (JVM, iOS, etc.) ...
}

    شیار 

    kotlin {
   androidLibrary {
       namespace = "com.example.kmpfirstlib"
       compileSdk = 33
       minSdk = 24

       withJava() // enable java compilation support
       withHostTestBuilder {}.configure {}
       withDeviceTestBuilder {
           it.sourceSetTreeName = "test"
       }

       compilations.configureEach {
           compilerOptions.options.jvmTarget.set(
               org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
           )
       }
   }

   sourceSets {
       androidMain {
           dependencies {
           }
       }
       androidHostTest {
           dependencies {
           }
       }
       androidDeviceTest {
           dependencies {
           }
       }
   }
   // ... other targets (JVM, iOS, etc.) ...
}

  5. پس از اعمال افزونه و پیکربندی بلوک kotlin ، پروژه Gradle خود را برای اعمال تغییرات همگام کنید.

یک ماژول جدید با افزونه ایجاد کنید

همچنین می توانید یک ماژول کتابخانه Multiplatform جدید Kotlin را مستقیماً در Android Studio ایجاد کنید. این افزونه های لازم را به طور خودکار اعمال می کند، از جمله افزونه Android-KMP. برای راهنمایی بیشتر در مورد نحوه ایجاد یک ماژول کتابخانه جدید KMP با Android Studio، به افزودن چند پلتفرم Kotlin به پروژه موجود مراجعه کنید.

برای اطلاعات بیشتر در مورد اکوسیستم چند پلتفرمی کلی و پیکربندی های پیشرفته تر، به مستندات رسمی چند پلتفرمی Kotlin مراجعه کنید.