إضافة Kotlin Multiplatform إلى مشروع حالي

لإنشاء وحدة Kotlin Multiplatform (KMP) ضمن مشروع Android، استخدِم نموذج Kotlin Multiplatform Shared Module المتوفّر في إصدار Meerkat من "استوديو Android" والإصدار 8.8.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android والإصدارات الأحدث.

يعمل نموذج الوحدة على إنشاء وحدة جديدة تلقائيًا بأقل قدر من الإعدادات التي تستهدف نظامَي التشغيل Android وiOS. تتيح KMP أيضًا استخدام أهداف أخرى، مثل أجهزة الكمبيوتر المكتبي والويب، والتي يمكنك إضافتها إلى الوحدة لاحقًا. للاطّلاع على القائمة الكاملة، يُرجى مراجعة ثبات المنصات المتوافقة. للإعلان عن هدف، يُرجى الاطّلاع على الأهداف في مرجع Multiplatform Gradle DSL.

ملاحظة: إذا أردت إنشاء تطبيق iOS، ستحتاج إلى جهاز macOS مثبَّت عليه Xcode. يجب أيضًا تثبيت محاكي iOS أو أن يكون لديك هاتف iPhone مُعدّ للتطوير لتشغيل التطبيق.

إعداد وحدة KMP المشتركة

لإنشاء وحدة KMP مشتركة، اتّبِع الخطوات التالية:

1. انقر على ملف (File) > جديد (New) > وحدة جديدة (New Module)
2. اختَر نموذج Kotlin Multiplatform Shared Module في لوحة النماذج:

الشكل 1. إنشاء وحدة KMP جديدة

في ما يلي الحقول في النموذج:

• اسم الوحدة: يحدّد اسم وحدة Gradle، بالإضافة إلى اسم إطار عمل iOS (يمكن تغييره لاحقًا)
• اسم الحزمة: يحدّد اسم الحزمة للملفات في هذه الوحدة
  1. انقر على إنهاء واسمح لـ Gradle بالمزامنة مع المشروع. قد يُطلب منك أيضًا إضافة ملفات الوحدة التي تم إنشاؤها حديثًا إلى التحكم في المصدر.

ملاحظة: تتضمّن الوحدة التي تم إنشاؤها بعض الدوال والاختبارات الأساسية للعناصر النائبة. تضمن دوال العناصر النائبة هذه تجميع الوحدة وتشغيلها بنجاح.

بعد اكتمال العملية، يعرض عرض المشروع في "استوديو Android" الوحدة المشتركة الجديدة مع مجموعة رموز المصدر لكل نظام أساسي.

الشكل 2. عرض المشروع الذي يعرض الوحدات المشتركة الجديدة

ربط الوحدة المشترَكة بتطبيق Android

لا يضيف معالج الوحدة الوحدة التي تم إنشاؤها حديثًا كعنصر تابع إلى أي وحدة حالية. كخطوة تالية، عليك ربط الوحدة المشتركة بإحدى وحدات Gradle الحالية على غرار تبعيات Android الأخرى:

dependencies {
    ...
    implementation(project(":shared"))
}

ملاحظة: إذا كان مشروعك يتيح ميزة دوال استرداد القيمة الآمنة من حيث النوع في Gradle، يمكنك الوصول إلى الوحدة المشتركة من خلال projects.shared.

بعد تفعيل الميزة، يمكنك الوصول إلى الرمز كالمعتاد. من تطبيق Android، يمكنك الوصول إلى الرمز البرمجي المتاح في androidMain أو في commonMain.

لمزيد من المعلومات حول بنية مشروع Kotlin Multiplatform، يُرجى الاطّلاع على أساسيات بنية مشروع Kotlin Multiplatform

إعداد الوحدة المشتركة في تطبيق iOS

لا يمكن لـ Swift استخدام وحدات Kotlin مباشرةً، بل يتطلب إنشاء إطار عمل ثنائي مجمّع.

ملاحظة: يتيح المكوّن الإضافي Kotlin Gradle أيضًا دمج Swift Package Manager أو دمج Cocoapods لمشاركة الرمز البرمجي الشائع الذي تم إنشاؤه للغة Kotlin وNative (iOS) واستخدامه.

يضبط نموذج الوحدة الجديد في "استوديو Android" الوحدة المشتركة لإنشاء إطار عمل لكل بنية من بنيات iOS. يمكنك العثور على الرمز التالي في ملف build.gradle.kts الخاص بالوحدة المشتركة:

val xcfName = "sharedKit"

iosX64 {
  binaries.framework {
    baseName = xcfName
  }
}

iosArm64 {
  binaries.framework {
    baseName = xcfName
  }
}

iosSimulatorArm64 {
  binaries.framework {
    baseName = xcfName
  }
}

راجِع بنية المشروع الهرمية للحصول على معلومات حول تحديد أنواع البُنى الأخرى.

ملاحظة: يُطلق على إطار عمل الناتج اسم sharedKit تلقائيًا، كما هو محدّد في ملف build.gradle.kts الخاص بالوحدة المشتركة. في مشروعك الخاص، يمكنك إعادة تسميته حسب الحاجة للتحكّم في المتغيّر xcfName.

ربط المكتبة المشتركة في مشروع iOS

لإتاحة الوصول إلى الرمز البرمجي المشترَك من مشروع iOS، أضِف مرحلة نص برمجي لإنشاء إطار عمل Kotlin قبل تجميع مصادر Swift:

ملاحظة: يمكنك أيضًا فتح مشروع Xcode بالنقر مرّتين على ملف xcodeproj في Finder.

1. انقر بزر الماوس الأيمن على الملف في استوديو Android واختَر فتح في (Open In) وفتح في التطبيق المرتبط (Open in Associated Application). سيؤدي ذلك إلى فتح تطبيق iOS في Xcode.

الشكل 3. الفتح في التطبيق المرتبط

1. افتح إعدادات المشروع بالنقر مرّتين على اسم المشروع في أداة التنقّل في المشروع

الشكل 4: مربّع حوار إعدادات مشروع Xcode

1. غيِّر الاسم التلقائي Run Script إلى Compile Kotlin Framework لتحديد وظيفة هذه المرحلة بشكل أفضل. انقر مرّتين فوق عنوان Run Script لتحريره.
2. وسِّع مرحلة الإنشاء، وفي حقل النص Shell، أدخِل رمز النص البرمجي التالي:

الشكل 5: تشغيل مرحلة إنشاء النص البرمجي

ملاحظة: ينقل cd "$SRCROOT/.." النص البرمجي إلى المجلد الجذر لمشروع KMP Gradle، وهو في هذه الحالة مجلد رئيسي. إذا كان مشروع iOS في مسار مختلف، عليك تعديل ذلك هنا.

1. اسحب مرحلة Run Script (تشغيل النص البرمجي) قبل مرحلة Compile Sources (تجميع المصادر).

   

   الشكل 6 تشغيل مرحلة إنشاء النص البرمجي قبل تجميع المصادر

2. أنشئ المشروع في Xcode بالنقر على ⌘B أو الانتقال إلى قائمة المنتج واختيار إنشاء.

عند نجاح عملية الإنشاء، سيظهر لك الرمز التالي.

الشكل 7. تم إنشاء الإصدار بنجاح

الوصول إلى الرمز المشترَك في تطبيق iOS

للتأكّد من أنّ تطبيق iOS يمكنه الوصول بنجاح إلى الرمز من الوحدة المشتركة، اتّبِع الخطوات التالية:

1. في مشروع iOS، افتح ملف ContentView.swift في: Sources/View/ContentView.swift
2. أضِف عبارة الاستيراد sharedKit في أعلى الملف.
3. عدِّل طريقة عرض النص لتضمين معلومات Platform_iosKt.platform() في السلسلة المعروضة على النحو التالي:

ملاحظة: تستخدم عملية دمج السلاسل في Swift بنية (الرمز).

يتحقّق هذا التعديل مما إذا كان بإمكان التطبيق استدعاء الدالة platform() من الوحدة المشتركة، والتي من المفترض أن تعرض "iOS" عند تشغيلها على نظام iOS الأساسي.

الشكل 8 محاكي Xcode يشغّل تطبيق iOS

موارد إضافية

• إذا كنت مبتدئًا في تطوير KMP، يمكنك الاطّلاع على مستندات KMP الرسمية لمزيد من الأدلة.
• إذا كنت مبتدئًا في تطوير تطبيقات iOS، يمكنك الاطّلاع على مستندات أساسيات Swift.
• للاطّلاع على المشاكل الشائعة في إعداد KMP، يُرجى مراجعة مقالة تحديد المشاكل وحلّها في دليل البدء السريع لـ KMP.
• للاطّلاع على نماذج التطبيقات، يُرجى الاطّلاع على نماذج Android Kotlin Multiplatform.