تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

إعداد المكوّن الإضافي لمكتبة Android Gradle في KMP

المكوّن الإضافي com.android.kotlin.multiplatform.library لنظام Gradle هو الأداة المتوافقة رسميًا لإضافة هدف Android إلى وحدة مكتبة Kotlin Multiplatform (KMP). ويسهِّل هذا المكوّن ضبط المشروع ويحسِّن أداء عملية الإنشاء ويوفِّر تكاملاً أفضل مع استوديو Android.

يعتمد استخدام المكوّن الإضافي com.android.library لتطوير KMP على واجهات برمجة التطبيقات الخاصة بالمكوّن الإضافي لنظام Gradle المتوافق مع Android والتي تم إيقافها نهائيًا وتتطلّب الموافقة في الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android والإصدارات الأحدث (الربع الرابع من عام 2025). من المتوقّع إزالة واجهات برمجة التطبيقات هذه في الإصدار 10.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android (النصف الثاني من عام 2026).

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

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

الميزات الأساسية والاختلافات

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

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

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

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

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

الحلول البديلة للميزات غير المتوافقة

عند مقارنة دمج KMP مع المكوّن الإضافي com.android.library، نجد أنّ بعض الميزات غير متوفّرة في المكوّن الإضافي com.android.kotlin.multiplatform.library. في ما يلي الحلول البديلة للميزات غير المتوافقة:

تنويعات التصميم

لا تتوفّر أنواع الإصدارات ونكهات المنتجات. ويرجع ذلك إلى أنّ المكوّن الإضافي الجديد يستخدم بنية صيغة واحدة، ما يسهّل عملية الضبط ويحسّن أداء عملية الإنشاء.

إذا كنت بحاجة إلى تنويعات التصميم، ننصحك بإنشاء وحدة مكتبة Android مستقلة باستخدام المكوّن الإضافي com.android.library، وضبط أنواع التصميم وصيغ المنتج داخل هذه الوحدة، ثم استخدامها كاعتمادية مشروع عادية من مجموعة رموز المصدر androidMain لمكتبة Kotlin Multiplatform. لمزيد من التفاصيل، يُرجى الاطّلاع على إنشاء مكتبة Android وضبط تنويعات التصميم.
ربط البيانات وربط العرض

هذه الميزات خاصة بإطار عمل واجهة المستخدم في Android، وهي مرتبطة ارتباطًا وثيقًا بنظام Android View وتخطيطات XML. باستخدام المكوّن الإضافي الجديد لمكتبة Android-KMP، ننصحك بالتعامل مع واجهة المستخدم باستخدام إطار عمل متعدّد المنصات مثل Compose Multiplatform. يُعدّ ربط البيانات وربط العرض من تفاصيل تنفيذ تطبيق Android النهائي، وليس من تفاصيل مكتبة قابلة للمشاركة.
دعم الإصدارات الأصلية

يركّز المكوّن الإضافي الجديد على إنشاء ملف AAR عادي لهدف Android. تتم معالجة دمج الرموز البرمجية الأصلية في Kotlin Multiplatform مباشرةً من خلال أهداف KMP الأصلية (مثل androidNativeArm64 وandroidNativeX86) وإمكانات التشغيل التفاعلي مع لغة C. إذا كنت بحاجة إلى تضمين رمز C/C++‎ أصلي، عليك تحديده كجزء من مجموعة رموز مصدر مشتركة أو أصلية وضبط إمكانية التشغيل التفاعلي مع لغة C ضمن مجموعة kotlin، بدلاً من استخدام آلية externalNativeBuild الخاصة بنظام Android.

بدلاً من ذلك، إذا كنت بحاجة إلى دعم الإصدار الأصلي من خلال externalNativeBuild، ننصحك بإنشاء وحدة com.android.library مستقلة يمكنك من خلالها دمج الرموز البرمجية الأصلية واستخدام هذه المكتبة المستقلة من مجموعة رموز المصدر androidMain لمشروع مكتبة Kotlin Multiplatform. لمزيد من التفاصيل، يُرجى الاطّلاع على إنشاء مكتبة Android وإضافة رمز C وC++‎ إلى مشروعك.
صف واحد (BuildConfig)

تكون ميزة "BuildConfig" مفيدة للغاية في البيئات المتعدّدة الصيغ. بما أنّ المكوّن الإضافي الجديد لمكتبة Kotlin Multiplatform لا يعتمد على الصيغ ولا يتيح أنواع الإصدارات ونكهات المنتجات، لم يتم تنفيذ هذه الميزة. كحلّ بديل، ننصحك باستخدام المكوّن الإضافي BuildKonfig أو حلول مشابهة من المنتدى لإنشاء بيانات وصفية لجميع الأهداف.

المتطلبات الأساسية

لاستخدام المكوّن الإضافي com.android.kotlin.multiplatform.library، يجب ضبط مشروعك على الحد الأدنى من الإصدارات التالية أو إصدارات أحدث:

المكوّن الإضافي لنظام Gradle المتوافق مع Android‏ (AGP): ‏ 8.10.0
المكوّن الإضافي لنظام Gradle المتوافق مع Kotlin‏ (KGP): ‏ 2.0.0

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

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

تعريف المكوّنات الإضافية في قائمة الإصدارات افتح ملف 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 = "9.4.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" }

طبِّق بيان المكوّن الإضافي في ملف الإصدار الجذر. افتح ملف 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 }
أنيق
// Root build.gradle file plugins { alias(libs.plugins.kotlin.multiplatform) apply false // Add the following alias(libs.plugins.android.kotlin.multiplatform.library) apply false }

طبِّق المكوّن الإضافي في ملف إصدار وحدة مكتبة 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)
}

أنيق

// Module-specific build.gradle file

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

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

ضبط هدف Android KMP اضبط مجموعة Kotlin Multiplatform (kotlin) لتحديد هدف Android. ضمن مجموعة kotlin، حدِّد هدف Android باستخدام android:

Kotlin

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

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

       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 {
   android {
       namespace = "com.example.kmpfirstlib"
       compileSdk = 33
       minSdk = 24

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

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

طبِّق التغييرات. بعد تطبيق المكوّن الإضافي وضبط مجموعة الرموز البرمجية kotlin، يجب مزامنة مشروع Gradle لتطبيق التغييرات.

نقل البيانات من المكوّن الإضافي القديم

يساعدك هذا الدليل في نقل البيانات من المكوّن الإضافي القديم com.android.library إلى المكوّن الإضافي com.android.kotlin.multiplatform.library.

ملاحظة: بالنسبة إلى إصدارات المكوّن الإضافي لنظام Gradle المتوافق مع Android الأقدم من 8.12.0، يكون قسم الإعدادات الخاص بهدف Android هو androidLibrary{}. بدءًا من الإصدار 8.12.0 من "مكوّن Android الإضافي في Gradle"، تم تقديم مجموعة جديدة من android{} لتحل محل androidLibrary{}. تم إيقاف androidLibrary{} نهائيًا منذ الإصدار 9.1.0-alpha09 من المكوّن الإضافي لنظام Gradle المتوافق مع Android، وستتم إزالته في إصدار مستقبلي. إذا كنت تستخدم الإصدار 8.12.0 أو إصدارًا أحدث من "مكوّن Android الإضافي في Gradle"، استخدِم android{}، وإلا استخدِم androidLibrary{}.

1. نقل المصادر

كان المكوّن الإضافي القديم يتيح لك استخدام مجموعات المصادر src/main وsrc/test وsrc/androidTest، بالإضافة إلى src/androidMain وsrc/androidHostTest وsrc/androidDeviceTest. يستخدم المكوّن الإضافي الجديد أدلة ملفات المصدر الأخيرة فقط، لذا ستحتاج إلى نقل المصادر من src/main إلى src/androidMain، ومن src/test إلى src/androidHostTest، ومن src/androidTest إلى src/androidDeviceTest.

2. ضبط أدلة المصادر والموارد المخصّصة

إذا كانت لديك مصادر أو موارد في أدلة غير عادية، فقد سبق لك ضبطها باستخدام مجموعة sourceSets. باستخدام المكوّن الإضافي الجديد، يمكنك استخدام الإضافة androidComponents لإضافة أدلة ملفات المصدر الثابتة إلى الصيغة.

يُرجى العِلم أنّه باستخدام المكوّن الإضافي الجديد، تضيف الطريقة addStaticSourceDirectory الدليل إلى القائمة الحالية لأدلة ملفات المصدر. باستخدام المكوّن الإضافي القديم، تستبدل الطريقة setSrcDirs القائمة، بينما تضيف الطريقة srcDir إليها.

Android-KMP

باستخدام المكوّن الإضافي الجديد، يمكنك استخدام مجموعة بيانات onVariants للتفاعل مع مصادر الصيغة.

// build.gradle.kts

androidComponents {
    onVariants { variant ->
        // Add a directory for Kotlin sources
        variant.sources.kotlin?.addStaticSourceDirectory("other/kotlin")

        // Add a directory for Android assets
        variant.sources.assets?.addStaticSourceDirectory("other/assets")
    }
}

المكوّن الإضافي القديم

باستخدام المكوّن الإضافي com.android.library، تم استخدام مجموعة الرموز البرمجية sourceSets لضبط أدلة ملفات المصدر أو إضافتها.

// build.gradle.kts

android {
    sourceSets {
        getByName("main") {
            // Replaces the directory for Kotlin sources.
            kotlin.setSrcDirs(listOf("other/kotlin"))

            // Appends a directory for assets.
            assets.srcDir("other/assets")
        }
    }
}

3- تحديد الاعتماديات

من المهام الشائعة تحديد التبعيات لمجموعات رموز المصدر الخاصة بنظام Android. يتطلّب المكوّن الإضافي الجديد وضع هذه العناصر بشكل صريح ضمن مجموعة sourceSets، على عكس مجموعة dependencies العامة التي تم استخدامها سابقًا.

Android-KMP

يعزّز المكوّن الإضافي الجديد البنية الأكثر تنظيمًا من خلال تجميع تبعيات Android ضمن مجموعة رموز المصدر androidMain. بالإضافة إلى مجموعة رموز المصدر الرئيسية، هناك مجموعتان من رموز المصدر للاختبار، يتم إنشاؤهما عند الطلب: androidDeviceTest وandroidHostTest (راجِع إعداد اختبارات المضيف والجهاز لمزيد من المعلومات).

// build.gradle.kts

kotlin {
    android {}
    //... other targets

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
        }

        // Dependencies are now scoped to the specific Android source set
        androidMain.dependencies {
            implementation("androidx.appcompat:appcompat:1.7.0")
            implementation("com.google.android.material:material:1.11.0")
        }
    }
}

تحتوي مجموعات رموز المصدر على عمليات تجميع بلغة Kotlin ذات الصلة باسم main وdeviceTest وhostTest. يمكن ضبط مجموعات رموز المصدر وعمليات التجميع في النص البرمجي للإصدار على النحو التالي:

// build.gradle.kts

kotlin {
    android {
        compilations.getByName("deviceTest") {
            kotlinOptions.languageVersion = "2.0"
        }
    }
}

المكوّن الإضافي القديم

باستخدام المكوّن الإضافي القديم، كان بإمكانك تحديد التبعيات الخاصة بنظام Android في مجموعة التبعيات ذات المستوى الأعلى، ما قد يؤدي أحيانًا إلى حدوث التباس في وحدة متعددة الأنظمة الأساسية.

// build.gradle.kts

kotlin {
  androidTarget()
  //... other targets
}

// Dependencies for all source sets were often mixed in one block
dependencies {
  // Common dependencies
  commonMainImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")

  // Android-specific dependencies
  implementation("androidx.appcompat:appcompat:1.7.0")
  implementation("com.google.android.material:material:1.11.0")
}

4. تفعيل موارد Android

لا يتم تلقائيًا تفعيل ميزة إتاحة موارد Android (مجلدات res) باستخدام المكوّن الإضافي الجديد لتحسين أداء عملية الإنشاء. يجب الموافقة لاستخدامها. يساعد هذا التغيير في ضمان عدم تحميل المشاريع التي لا تتطلّب موارد خاصة بنظام Android أعباء إضافية مرتبطة بعملية الإنشاء.

Android-KMP

يجب تفعيل معالجة موارد Android بشكل صريح. يجب وضع الموارد في src/androidMain/res.

// build.gradle.kts

kotlin {
  android {
    // ...
    // Enable Android resource processing
    androidResources {
      enable = true
    }
  }
}

// Project Structure
// └── src
//     └── androidMain
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

المكوّن الإضافي القديم

تم تفعيل معالجة الموارد تلقائيًا. يمكنك إضافة دليل res في src/main على الفور والبدء في إضافة ملفات XML قابلة للرسم وقيم وما إلى ذلك.

// build.gradle.kts

android {
    namespace = "com.example.library"
    compileSdk = 34
    // No extra configuration was needed to enable resources.
}

// Project Structure
// └── src
//     └── main
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

5. ضبط اختبارات المضيف والجهاز

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

يساعد نموذج الموافقة هذا في التأكّد من أنّ مشروعك يظل بسيطًا ولا يتضمّن سوى منطق الإصدار ومجموعات رموز المصدر التي تستخدمها بشكل نشط.

Android-KMP

باستخدام المكوّن الإضافي الجديد، يمكنك تفعيل الاختبارات وضبطها داخل مجموعة kotlin.android. هذا يجعل الإعداد أكثر وضوحًا ويتجنب إنشاء مكونات اختبار غير مستخدمة. تصبح مجموعة رموز المصدر androidUnitTest androidHostTest (يتغيّر دليل الاختبار من src/androidUnitTest إلى src/androidHostTest)، وتصبح androidInstrumentedTest androidDeviceTest (يتغيّر دليل الاختبار من src/androidInstrumentedTest إلى src/androidDeviceTest).

// build.gradle.kts

kotlin {
  android {
    // ...

    // Opt-in to enable and configure host-side (unit) tests
    withHostTest {
      isIncludeAndroidResources = true
    }

    // Opt-in to enable and configure device-side (instrumented) tests
    withDeviceTest {
      instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
      execution = "HOST"
    }
  }
}

// Project Structure (After Opt-in)
// └── src
//     ├── androidHostTest
//     └── androidDeviceTest

المكوّن الإضافي القديم

باستخدام المكوّن الإضافي com.android.library، يتم إنشاء مجموعتَي رموز المصدر androidUnitTest وandroidInstrumentedTest تلقائيًا. يمكنك ضبط سلوكها داخل مجموعة android، عادةً باستخدام لغة DSL الخاصة بـ testOptions.

// build.gradle.kts

android {
  defaultConfig {
    // Runner was configured in defaultConfig
    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
  }

  testOptions {
    // Configure unit tests (for the 'test' source set)
    unitTests.isIncludeAndroidResources = true

    // Configure device tests (for the 'androidTest' source set)
    execution = "HOST"
  }
}

// Project Structure (Defaults)
// └── src
//     ├── test
//     └── androidTest

6. تفعيل تجميع مصدر Java

إذا كانت مكتبة KMP بحاجة إلى تجميع مصادر Java لهدف Android، يجب تفعيل هذه الوظيفة صراحةً باستخدام المكوّن الإضافي الجديد. يُرجى العِلم أنّ هذا الإجراء يتيح تجميع ملفات Java الموجودة مباشرةً في مشروعك، وليس في تبعياته. تتغيّر أيضًا طريقة ضبط الإصدار المستهدَف من جهاز Java الافتراضي (JVM) لبرنامج تجميع Java وKotlin.

Android-KMP

يجب الموافقة على تجميع Java من خلال استدعاء withJava(). يتم الآن ضبط هدف JVM مباشرةً داخل مجموعة kotlin { android {} } لإعداد أكثر توحيدًا. ينطبق ضبط jvmTarget هنا على كل من تجميع Kotlin وJava لهدف Android.

// build.gradle.kts

kotlin {
  android {
    //  Opt-in to enable Java source compilation
    withJava()
    // Configure the JVM target for both Kotlin and Java sources
    compilerOptions {
      jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8)
    }
  }
  // ...
}

// Project Structure:
// └── src
//     └── androidMain
//         ├── kotlin
//         │   └── com/example/MyKotlinClass.kt
//         └── java
//             └── com.example/MyJavaClass.java

المكوّن الإضافي القديم

تم تفعيل تجميع Java تلقائيًا. تم ضبط هدف JVM لكل من مصادر Java وKotlin في مجموعة android باستخدام compileOptions.

// build.gradle.kts

android {
  // ...
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

kotlin {
  androidTarget {
    compilations.all {
      kotlinOptions.jvmTarget = "1.8"
    }
  }
}

7. التفاعل مع تنويعات التصميم باستخدام `androidComponents`

لا تزال إضافة androidComponents متاحة للتفاعل مع عناصر الإصدار آليًا. على الرغم من أنّ واجهة برمجة التطبيقات Variant لم تتغيّر كثيرًا، إلا أنّ واجهة AndroidKotlinMultiplatformVariant الجديدة أصبحت محدودة أكثر لأنّ المكوّن الإضافي ينتج صيغة واحدة فقط.

وبالتالي، لم تعُد الخصائص ذات الصلة بأنواع الإصدارات وصيغ المنتجات متاحة في عنصر التنويع.

Android-KMP

تكرّر الآن كتلة onVariants صيغة واحدة. سيظل بإمكانك الوصول إلى السمات الشائعة مثل name وartifacts، ولكن ليس السمات الخاصة بنوع الإصدار.

// build.gradle.kts

androidComponents {
  onVariants { variant ->
      val artifacts = variant.artifacts
  }
}

المكوّن الإضافي القديم

باستخدام صيغ متعددة، يمكنك الوصول إلى السمات الخاصة بنوع الإصدار لضبط المهام.

// build.gradle.kts

androidComponents {
  onVariants(selector().withBuildType("release")) { variant ->
    // ...
  }
}

8. اختيار صيغ تبعيات مكتبة Android

تُنتج مكتبة KMP صيغة واحدة لنظام التشغيل Android. ومع ذلك، قد تعتمد على مكتبة Android عادية (com.android.library) تحتوي على صيغ متعددة (مثل free/paid من صيغ المنتج). يُعدّ التحكّم في كيفية اختيار مشروعك لنسخة من هذه التبعية من المتطلبات الشائعة.

Android-KMP

يجمع المكوّن الإضافي الجديد هذا المنطق ويوضّحه ضمن مجموعة kotlin.android.localDependencySelection. ويجعل ذلك من السهل معرفة أي من نُسخ التبعيات الخارجية سيتم اختيارها لمكتبة KMP ذات النسخة الواحدة.

// build.gradle.kts
kotlin {
  android {
    localDependencySelection {
      // For dependencies with multiple build types, select 'debug' first, and 'release' in case 'debug' is missing
      selectBuildTypeFrom.set(listOf("debug", "release"))

      // For dependencies with a 'type' flavor dimension...
      productFlavorDimension("type") {
        // ...select the 'typeone' flavor.
        selectFrom.set(listOf("typeone"))
      }
    }
  }
}

المكوّن الإضافي القديم

لقد ضبطت استراتيجيات اختيار التبعيات داخل مجموعات buildTypes and productFlavors. يتطلّب ذلك غالبًا استخدام missingDimensionStrategy لتوفير صيغة تلقائية لسمة لا تتوفّر في مكتبتك، أو matchingFallbacks ضمن صيغة معيّنة لتحديد ترتيب البحث.

يُرجى الاطّلاع على حلّ أخطاء المطابقة للحصول على مزيد من المعلومات التفصيلية حول استخدام واجهة برمجة التطبيقات.

9. إضافة اعتماديات معاينة Compose

عادةً، نريد أن يكون لدينا مكتبات محددة مخصصة لبيئة التطوير المحلية لمنع تسرب الأدوات الداخلية إلى الأداة النهائية المنشورة. يصبح هذا الأمر صعبًا مع المكوّن الإضافي الجديد لـ KMP على Android لأنّه يزيل بنية نوع الإصدار المستخدَمة لفصل تبعيات التطوير عن رمز الإصدار.

Android-KMP

لإضافة تبعية للتطوير والاختبار المحليين فقط، أضِف التبعية مباشرةً إلى إعدادات مسار فئة وقت التشغيل (في كتلة dependencies ذات المستوى الأعلى) لعملية تجميع Android الرئيسية. يساعد ذلك في ضمان توفّر التبعية في وقت التشغيل (على سبيل المثال، لأدوات مثل Compose Preview)، ولكنّها ليست جزءًا من مسار فئة التجميع أو واجهة برمجة التطبيقات المنشورة لمكتبتك.

// build.gradle.kts
dependencies {
  "androidRuntimeClasspath"(libs.androidx.compose.ui.tooling)
}

المكوّن الإضافي القديم

بالنسبة إلى مشاريع Kotlin Multiplatform التي تستخدم المكوّن الإضافي com.android.library لاستهداف Android، يجب استخدام الإعداد debugImplementation الذي يحدّد نطاق التبعية لنوع الإصدار المخصص لتصحيح الأخطاء ويمنع تضمينه في صيغة إصدار المكتبة التي يستخدمها المستهلكون.

// build.gradle.kts
dependencies {
  debugImplementation(libs.androidx.compose.ui.tooling)
}

10. ضبط هدف JVM لهدف KMP Android

يضبط المكوّن الإضافي المتوافق مع Android KMP هدف جهاز Java الافتراضي باستخدام android.compilerOptions.jvmTarget، والذي ينطبق على كل من Java وKotlin، ما يسهّل عملية الضبط مقارنةً بكتل compileOptions وkotlinOptions المنفصلة في مشاريع Android الخالصة.

Android-KMP

عند العمل على مشروع Kotlin Multiplatform (KMP) يتضمّن هدف Android، لديك عدة طرق لضبط إصدار هدف JVM لكل من برنامج تجميع Kotlin وJava. من المهم فهم نطاق هذه الإعدادات وتسلسلها الهرمي لإدارة توافق الرمز الثانوي لمشروعك.

في ما يلي الطرق الأساسية الثلاث لضبط هدف JVM، مرتّبة من الأقل إلى الأعلى أولوية. تُطبَّق قيم استهداف JVM التي لها أولوية أعلى على مجموعة فرعية أصغر من الاستهدافات التي تم ضبطها، وتلغي القيم التي لها أولوية أقل، ما يعني أنّه يمكنك ضبط إصدارات JVM مختلفة لاستهدافات وعمليات تجميع مختلفة ضمن الاستهدافات في مشروعك.

استخدام سلسلة أدوات kotlin (الأولوية الأدنى)

الطريقة الأكثر شيوعًا لضبط هدف JVM هي تحديد سلسلة الأدوات في مجموعة kotlin ضمن ملف build.gradle.kts. يحدّد هذا النهج الهدف لكل من مهام تجميع Kotlin وJava في جميع الأهداف المستندة إلى JVM في مشروعك، بما في ذلك Android.

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

يؤدي هذا الإعداد إلى جعل كل من kotlinc وjavac يستهدفان JVM 21. إنّها طريقة رائعة لوضع أساس متّسق لمشروعك بأكمله.

استخدام خيارات برنامج التجميع على مستوى الاستهداف في Android (أولوية متوسطة)

يمكنك تحديد هدف JVM خصيصًا لهدف Android KMP ضمن مجموعة android. يتجاوز هذا الإعداد إعدادات jvmToolchain على مستوى المشروع، وينطبق على جميع عمليات تجميع Android.

// build.gradle.kts
kotlin {
    android {
        compilerOptions {
            jvmTarget.set(JvmTarget.JVM_11)
        }
    }
}

في هذه الحالة، حتى إذا تم ضبط jvmToolchain على إصدار مختلف، سيتم تجميع رمز Kotlin وJava الخاص بهدف Android لاستهداف JVM 11.

استخدام خيارات برنامج التجميع على مستوى التجميع (الأولوية القصوى)

للحصول على تحكّم أكثر دقة، يمكنك ضبط خيارات برنامج التجميع على أساس كل عملية تجميع (على سبيل المثال، على androidMain أو androidHostTest فقط). ويكون ذلك مفيدًا إذا كانت عملية تجميع معيّنة تحتاج إلى استهداف إصدار مختلف من "جهاز Java الافتراضي" (JVM). يلغي هذا الإعداد كلاً من سلسلة أدوات Kotlin وخيارات مستوى الاستهداف في Android.

// build.gradle.kts
kotlin {
    android {
        compilations.all {
            compileTaskProvider.configure {
                compilerOptions.jvmTarget.set(JvmTarget.JVM_11)
            }
        }
    }
}

يساعد هذا الإعداد في ضمان استخدام جميع عمليات التجميع ضمن هدف Android لإصدار JVM 11، ما يوفّر تحكّمًا دقيقًا.

المكوّن الإضافي القديم

في مشروع KMP الذي يستخدم المكوّن الإضافي العادي لمكتبة Android (com.android.library)، تختلف الإعدادات قليلاً عن تلك التي يتم استخدامها في المكوّن الإضافي المتوافق مع Android في KMP (ولكنّها متشابهة من الناحية النظرية).

استخدام سلسلة أدوات Kotlin

تعمل طريقة kotlin.jvmToolchain() بشكل مماثل، حيث تضبط sourceCompatibility وtargetCompatibility للغة Java و jvmTarget للغة Kotlin. ننصحك باستخدام هذا النهج.

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

compileOptions وkotlinOptions

إذا كنت لا تستخدم سلسلة أدوات Kotlin، عليك ضبط أهداف JVM باستخدام مجموعات منفصلة لكل من Java وKotlin.

// build.gradle.kts
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = "11"
    }
}

11. نشر قواعد الاحتفاظ بالبيانات للمستهلكين

إذا كانت مكتبة KMP بحاجة إلى توفير قواعد الاحتفاظ بالمستهلكين (مثل قواعد ProGuard لـ R8) للمستهلكين، عليك تفعيل النشر صراحةً باستخدام المكوّن الإضافي الجديد. في السابق، كانت قواعد الاحتفاظ بالمستهلك تُنشر تلقائيًا إذا تم تحديدها.

Android-KMP

باستخدام المكوّن الإضافي الجديد، يجب ضبط optimization.consumerKeepRules.publish = true وتحديد ملفات القواعد ضمن مجموعة consumerKeepRules لنشر قواعد الاحتفاظ بالمستهلك.

// build.gradle.kts
kotlin {
  android {
    optimization {
      consumerKeepRules.apply {
        publish = true
        file("consumer-proguard-rules.pro")
      }
    }
  }
}

المكوّن الإضافي القديم

باستخدام com.android.library، يتم نشر أي ملفات قواعد محدّدة باستخدام consumerProguardFiles في android.defaultConfig في نواتج المكتبة بشكل تلقائي.

// build.gradle.kts
android {
  defaultConfig {
    consumerProguardFiles("consumer-proguard-rules.pro")
  }
}

12. نشر مكتبتك على Maven

إذا كنت تخطّط لنشر مكتبة KMP على Maven لتستخدمها مشاريع أخرى، تختلف العملية حسب ما إذا كنت تستخدم المكوّن الإضافي الجديد Android-KMP أو المكوّن الإضافي القديم.

Android-KMP

يتكامل المكوّن الإضافي com.android.kotlin.multiplatform.library مع آليات النشر العادية في Kotlin Multiplatform. لا توجد خطوات خاصة بنظام Android مطلوبة بخلاف عملية نشر مكتبة KMP العادية.

لنشر مكتبتك، اتّبِع المستندات الرسمية من JetBrains: إعداد عملية النشر لمكتبة متوافقة مع أجهزة متعدّدة.

المكوّن الإضافي القديم

عند استخدام com.android.library لهدف Android في مشروع KMP، عليك اتّباع دليل نشر مكتبة Android العادي لإعداد ونشر العنصر الخاص بنظام Android (.aar).

للحصول على تعليمات تفصيلية، يُرجى الاطّلاع على مقالة إعداد المكتبة للإصدار.

مرجع واجهة برمجة التطبيقات للمكوّنات الإضافية

يحتوي المكوّن الإضافي الجديد على واجهة برمجة تطبيقات مختلفة عن com.android.library. للحصول على معلومات تفصيلية عن لغة DSL والواجهات الجديدة، يُرجى الاطّلاع على مراجع واجهة برمجة التطبيقات:

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

في ما يلي المشاكل المعروفة التي قد تحدث عند تطبيق المكوّن الإضافي الجديد "com.android.kotlin.multiplatform.library":

تعذُّر معاينة Compose عند استخدام المكوّن الإضافي الجديد android-KMP
- تم إصلاح المشكلة في Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 وAndroid Gradle Plugin 9.0.0-alpha13
‫NullPointerException في معاينات Compose Multiplatform مع المكوّن الإضافي com.android.kotlin.multiplatform.library
- تم إصلاح المشكلة في Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 وAndroid Gradle Plugin 9.0.0-alpha13
تخزِّن منصة KMP حلّ تبعية التجميع الشائعة في ذاكرة التخزين المؤقت للإعدادات، ما يؤدي إلى حدوث خطأ عند إلغاء التسلسل (على أجهزة Android فقط)
- تم إصلاح المشكلة في Kotlin Gradle Plugin 2.3.0-Beta2
إتاحة instrumented sourceSetTree لهدف androidLibrary
- تم إصلاح المشكلة في Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 وAndroid Gradle Plugin 9.0.0-alpha13

التطبيقات المقترَحة لك

ملاحظة: يتم عرض نص الرابط عندما يكون JavaScript غير مفعَّل
إعداد البيئة
إضافة وحدة KMP إلى مشروع

إعداد المكوّن الإضافي لمكتبة Android Gradle في KMP تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الميزات الأساسية والاختلافات

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

الحلول البديلة للميزات غير المتوافقة

المتطلبات الأساسية

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

Kotlin

أنيق

Kotlin

أنيق

Kotlin

أنيق

نقل البيانات من المكوّن الإضافي القديم

1. نقل المصادر

2. ضبط أدلة المصادر والموارد المخصّصة

Android-KMP

المكوّن الإضافي القديم

3- تحديد الاعتماديات

Android-KMP

المكوّن الإضافي القديم

4. تفعيل موارد Android

Android-KMP

المكوّن الإضافي القديم

5. ضبط اختبارات المضيف والجهاز

Android-KMP

المكوّن الإضافي القديم

6. تفعيل تجميع مصدر Java

Android-KMP

المكوّن الإضافي القديم

7. التفاعل مع تنويعات التصميم باستخدام androidComponents

Android-KMP

المكوّن الإضافي القديم

8. اختيار صيغ تبعيات مكتبة Android

Android-KMP

المكوّن الإضافي القديم

9. إضافة اعتماديات معاينة Compose

Android-KMP

المكوّن الإضافي القديم

10. ضبط هدف JVM لهدف KMP Android

Android-KMP

المكوّن الإضافي القديم

11. نشر قواعد الاحتفاظ بالبيانات للمستهلكين

Android-KMP

المكوّن الإضافي القديم

12. نشر مكتبتك على Maven

Android-KMP

المكوّن الإضافي القديم

مرجع واجهة برمجة التطبيقات للمكوّنات الإضافية

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

التطبيقات المقترَحة لك

إعداد المكوّن الإضافي لمكتبة Android Gradle في KMP

7. التفاعل مع تنويعات التصميم باستخدام `androidComponents`