نقل البيانات إلى المكوّن الإضافي لمكتبة Android-KMP

تتضمّن منصة Kotlin المتعدّدة Gradle مكوّنًا إضافيًا لضبط إعدادات وحدة المكتبة.

المكوّن الإضافي com.android.kotlin.multiplatform.library هو البديل الرسمي للطريقة السابقة لإضافة استهدافات Android إلى مكتبات KMP باستخدام المكوّن الإضافي العادي لنظام Gradle الخاص بمكتبة Android (com.android.library).

تم إيقاف الطريقة السابقة نهائيًا واستبدالها بالمكوّن الإضافي، والذي يُشار إليه أيضًا باسم مكوّن Android-KMP الإضافي. لن يكون بإمكانك مواصلة استخدام com.android.library المكوّن الإضافي لـ KMP، ولن تستفيد من التحديثات والتحسينات المستقبلية.

للانتقال إلى هذا المكوّن الإضافي، يُرجى الرجوع إلى قسم تطبيق المكوّن الإضافي Android-KMP.

الميزات والاختلافات الرئيسية

تم تصميم المكوّن الإضافي Android-KMP خصيصًا لمشاريع KMP، ويختلف عن المكوّن الإضافي com.android.library العادي في عدة جوانب رئيسية:

  • بنية الإصدار الفردي: تستخدم الإضافة إصدارًا واحدًا، ما يؤدي إلى إزالة التوافق مع نكهات المنتجات وأنواع الإصدارات، ما يسهّل عملية الإعداد ويحسّن أداء الإصدار.

  • محسَّن لمنصّة KMP: تم تصميم المكوّن الإضافي لمكتبات KMP، مع التركيز على رموز Kotlin البرمجية المشترَكة وإمكانية التشغيل التفاعلي، مع إغفال إمكانية استخدام الإصدارات الأصلية الخاصة بنظام Android وAIDL وRenderScript.

  • الاختبارات غير مفعَّلة تلقائيًا: يتم إيقاف كل من اختبارات الوحدات واختبارات الأجهزة (الأدوات) تلقائيًا لتحسين سرعة الإنشاء. يمكنك تفعيلها إذا لزم الأمر.

  • لا توجد إضافة Android من المستوى الأعلى: تتم معالجة الإعدادات باستخدام كتلة androidLibrary ضمن Gradle KMP DSL، ما يحافظ على بنية متسقة لمشروع KMP. ما مِن حظر لإضافة android من المستوى الأعلى.

  • تفعيل تجميع Java: يتم إيقاف تجميع Java تلقائيًا. استخدِم withJava() في حظر androidLibrary لتفعيله. يؤدي ذلك إلى تحسين أوقات الإنشاء عندما لا تكون هناك حاجة إلى تجميع Java.

مزايا المكوّن الإضافي لمكتبة Android-KMP

يوفّر المكوّن الإضافي Android-KMP المزايا التالية لمشاريع KMP:

  • تحسين أداء الإصدار وثباته: تم تصميم هذه الميزة لتحسين سرعات الإصدار وتعزيز الثبات في مشاريع KMP. يساهم التركيز على سير عمل KMP في عملية إنشاء أكثر كفاءة وموثوقية.

  • تكامل محسّن مع بيئة التطوير المتكاملة (IDE): يوفّر هذا التكامل إمكانات أفضل لإكمال الرموز البرمجية والتنقّل وتصحيح الأخطاء وتجربة أفضل بشكل عام للمطوّرين عند استخدام مكتبات KMP على Android.

  • تبسيط إعدادات المشروع: يسهّل المكوّن الإضافي عملية الإعداد لمشاريع KMP من خلال إزالة التعقيدات الخاصة بنظام Android، مثل خيارات الإنشاء. يؤدي ذلك إلى إنشاء ملفات إصدار أنظف وأسهل في الصيانة. في السابق، كان استخدام المكوّن الإضافي com.android.library في مشروع KMP يؤدي إلى إنشاء أسماء مربكة لمجموعات المصادر، مثل androidAndroidTest. لم يكن أسلوب التسمية هذا بديهيًا للمطوّرين الذين يعرفون بنى مشاريع KMP العادية.

تطبيق إضافة Android-KMP على وحدة حالية

لتطبيق المكوّن الإضافي Android-KMP على وحدة مكتبة KMP حالية، اتّبِع الخطوات التالية:

  1. تعريف المكوّنات الإضافية في قائمة الإصدارات: افتح ملف TOML الخاص بكتالوج الإصدارات (عادةً gradle/libs.versions.toml) وأضِف قسم تعريفات المكوّن الإضافي:

    # To check the version number of the latest Kotlin release, go to
# https://kotlinlang.org/docs/releases.html

[versions]
androidGradlePlugin = "8.12.0"
kotlin = "KOTLIN_VERSION"

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

  2. تطبيق بيان المكوّن الإضافي في ملف الإصدار الجذر: افتح الملف build.gradle.kts الموجود في الدليل الجذر لمشروعك. أضِف أسماء المكوّنات الإضافية البديلة إلى الحظر plugins باستخدام apply false. ويتيح ذلك استخدام أسماء مستعارة للمكوّن الإضافي في جميع المشاريع الفرعية بدون تطبيق منطق المكوّن الإضافي على المشروع الرئيسي نفسه.

    Kotlin

    // Root build.gradle.kts file

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

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

    Groovy

    // Root build.gradle file

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

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

  3. تطبيق المكوّن الإضافي في ملف إنشاء وحدة مكتبة KMP افتح ملف build.gradle.kts في وحدة مكتبة KMP وطبِّق المكوّن الإضافي في أعلى الملف ضمن كتلة plugins:

    Kotlin

    // Module-specific build.gradle.kts file

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

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

    Groovy

    // Module-specific build.gradle file

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

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

  4. ضبط هدف KMP لنظام التشغيل Android اضبط كتلة Kotlin Multiplatform (kotlin) لتحديد هدف Android. ضِمن كتلة kotlin، حدِّد هدف Android باستخدام androidLibrary:

    Kotlin

    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.) ...
}

    Groovy

    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 لتطبيق التغييرات.