نقل البيانات إلى المكوّن الإضافي لبرنامج "إدارة الموافقة" على Android

في السابق، كانت الطريقة الوحيدة لدمج Android في مشروع KMP هي استخدام المكوّن الإضافي العادي لنظام Gradle المتوافق مع مكتبة Android: com.android.library. ومع ذلك، تمّ الآن إيقاف هذا الأسلوب نهائيًا لصالح المكوّن الإضافي المخصّص com.android.kotlin.multiplatform.library، والذي يُشار إليه أيضًا باسم مكوّن Android-KMP الإضافي. يشرح هذا الدليل كيفية نقل البيانات إلى الإضافة الجديدة.

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

تم تصميم المكوّن الإضافي لنظام التشغيل Android‏ (com.android.kotlin.multiplatform.library) خصيصًا لمشاريع KMP، ويختلف عن المكوّن الإضافي التقليدي com.android.library في عدة جوانب رئيسية:

  • بنية الصيغة الواحدة: يعمل المكوّن الإضافي باستخدام صيغة واحدة، ويسهّل عملية الإنشاء من خلال إزالة التوافق مع أنواع الإصدارات المخصّصة للمنتج وأنواع الإنشاء الشائعة في مشاريع مكتبة Android العادية. ويؤدي ذلك إلى تبسيط عملية الإعداد وتحسين أداء عملية إنشاء مكتبات KMP لنظام Android.
  • محسَّن لـ KMP: تم تصميم المكوّن الإضافي خصيصًا لمكتبات Kotlin المتعددة المنصات، مع التركيز على رمز Kotlin المشترَك والتشغيل التفاعلي. ونتيجةً لذلك، لا تتيح هذه الميزة استخدام الإصدارات الأصلية المخصّصة لنظام التشغيل Android وAIDL (لغة تعريف واجهة Android) وRenderScript، والتي لا تتعلّق عادةً بسياق الرمز المشترَك في KMP.
  • الاختبارات غير مفعّلة تلقائيًا: لتحسين سرعة الإنشاء في بيئة متعددة المنصات، تكون الاختبارات غير مفعّلة تلقائيًا. يمكنك تحديدًا تفعيل الاختبارات إذا لزم الأمر لمشروعك. وينطبق ذلك على كلّ من الاختبارات على المضيف (اختبارات الوحدة) والاختبارات على الجهاز (اختبارات الأدوات).
  • عدم توفّر إضافة Android ذات مستوى أعلى: لا ينشئ المكوّن الإضافي إضافة android ذات مستوى أعلى في ملفات إنشاء Gradle. تتم معالجة الإعداد باستخدام وحدة androidLibrary ضمن لغة Kotlin DSL المخصّصة للأنظمة الأساسية المتعددة، مع الحفاظ على هيكل مشروع KMP متّسق.
  • تفعيل ميزة تجميع Java: لا تكون ميزة تجميع Java مفعّلة تلقائيًا. إذا كانت مكتبة KMP تحتاج إلى تجميع رمز برمجي يستند إلى Java، عليك تفعيلها صراحةً باستخدام واجهة برمجة التطبيقات withJava() ضمن كتلة الإعدادات androidLibrary في كتلة kotlin. يتيح ذلك التحكّم بشكل أدق في عملية الترجمة compiling ويمكن أن يُحسِّن أوقات التصميم عندما لا يكون ترجمة الرمز البرمجي المستنِد إلى Java مطلوبة.

مزايا نقل البيانات

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

  • تحسين أداء عملية الإنشاء وثباتها: تم تصميم المكوّن الإضافي لـ Android-KMP لتحسين سرعات الإنشاء وتعزيز الثبات في مشاريع KMP. تساهم بنيته المبسّطة وتركيزه على سير عمل "إدارة الأداء في التسويق" في توفير عملية إنشاء أكثر فعالية وموثوقية.
  • دمج محسّن لواجهة بيئة التطوير المتكاملة: يقدّم المكوّن الإضافي عملية دمج ممتازة مع IDE لأجل IDE وKotlin الأخرى. ويؤدي ذلك إلى تحسين إكمال الرموز البرمجية، والتنقّل، وتصحيح الأخطاء، وتجربة المطوّر بشكل عام عند العمل مع مكتبات KMP Android.
  • إعداد المشروع المبسّط: من خلال إزالة الصعوبات المتعلّقة بنظام Android، مثل الأسعار المتغيرة، يسهّل المكوّن الإضافي لنظام Android-KMP عملية الإعداد لمشاريع KMP. ويؤدي ذلك إلى إنشاء ملفات إنشاء أكثر وضوحًا وسهولة في الصيانة، وإلى تقليل منحنى التعلّم للمطوّرين المبتدئين في تطوير تطبيقات Android باستخدام KMP. في السابق، عند دمج Android في مشروع KMP باستخدام المكوّن الإضافي com.android.library، كان التفاعل بين المكوّن الإضافي لنظام Gradle المتوافق مع Android والمكوّن الإضافي لنظام Gradle المتوافق مع Kotlin ضمن بنية الأنظمة الأساسية المتعددة يؤدي في بعض الأحيان إلى ظهور أسماء مضلِّلة لمجموعات المصادر. على سبيل المثال، تم تسمية مجموعة المصادر المخصّصة لضبط اختبارات Android المزوّدة بأدوات قياس androidAndroidTest. كان نظام التسمية هذا أقل سهولة للمطوّرين الملمّين بتصاميم مشاريع KMP العادية.
  • الحلّ الرسمي والمُقترَح: المكوّن الإضافي com.android.kotlin.multiplatform.library هو البديل الرسمي للطريقة السابقة لإضافة استهدافات Android إلى مكتبات KMP باستخدام المكوّن الإضافي com.android.library. لن تعود شركة JetBrains توفّر الدعم لاستخدام المكوّن com.android.library الإضافي في KMP، ولن تستفيد من التحديثات والتحسينات المستقبلية.

تطبيق المكوّن الإضافي Android-KMP على مشروع

هناك طريقتان أساسيتان لتطبيق المكوّن الإضافي Android-KMP على مشروعك:

تطبيق المكوّن الإضافي على وحدة حالية

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

  1. الإفصاح عن المكوّنات الإضافية في قائمة الإصدارات افتح ملف TOML الخاص بقائمة الإصدارات (عادةً gradle/libs.versions.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) المتوفّر في الدليل الجذر لمشروعك. أضِف الأسماء البديلة للمكوّنات الإضافية إلى plugins الوحدة باستخدام apply false. ويؤدي ذلك إلى إتاحة الأسماء البديلة للمكوّنات الإضافية لجميع المشاريع الفرعية بدون تطبيق منطق المكوّن الإضافي على المشروع الجذر نفسه.

    Kotlin

    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
}

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

    Kotlin

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

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

    رائع

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

    رائع

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

إنشاء وحدة جديدة باستخدام المكوّن الإضافي

يمكنك أيضًا إنشاء وحدة مكتبة جديدة لنظام Kotlin المتوافق مع أنظمة التشغيل المتعددة مباشرةً في IDE Android Studio. يؤدي ذلك إلى تطبيق المكوّنات الإضافية اللازمة تلقائيًا، بما في ذلك المكوّن الإضافي Android-KMP. للحصول على مزيد من الإرشادات حول كيفية إنشاء ملف برمجي جديد لنظام KMP وحدة باستخدام Android Studio، اطّلِع على مقالة إضافة Kotlin Multiplatform إلى مشروع حالي.

لمزيد من المعلومات حول المنظومة المتكاملة الشاملة للأنظمة الأساسية المتعددة والإعدادات المتقدّمة، اطّلِع على مستندات Kotlin Multiplatform الرسمية.