إعداد المكوّن الإضافي لمكتبة 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. إذا كنت بحاجة إلى نقل البيانات من واجهات برمجة التطبيقات القديمة، يُرجى الاطّلاع على دليل نقل البيانات.

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

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

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

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

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

• عدم توفّر إضافة Android من المستوى الأعلى: تتم معالجة الإعدادات باستخدام كتلة androidLibrary ضمن لغة DSL الخاصة بمنصة KMP في Gradle، ما يحافظ على اتّساق بنية مشروع 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

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

• يتعذّر عرض معاينة الإنشاء عند استخدام المكوّن الإضافي الجديد android-KMP

• NullPointerException في معاينات Compose Multiplatform باستخدام المكوّن الإضافي com.android.kotlin.multiplatform.library

• يخزِّن KMP عملية تحديد تبعية التجميع الشائعة في ذاكرة التخزين المؤقت للإعدادات، ما يؤدي إلى حدوث خطأ عند إلغاء التسلسل (نظام التشغيل Android فقط)

• إتاحة استخدام sourceSetTree الذي يتضمّن أدوات لإنشاء مكتبة Android

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

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

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

تطبيق المكوّن الإضافي 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.13.2"
   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"
          }
   
          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"
          }
   
          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 لتطبيق التغييرات.

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

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

‫1. تحديد الاعتماديات

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

// build.gradle.kts

kotlin {
    androidLibrary {}
    //... 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")
        }
    }
}

// build.gradle.kts

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

// 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")
}

‫2- تفعيل "موارد Android"

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

// build.gradle.kts

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

// Project Structure
// └── src
//     └── androidMain
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.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

3- ضبط اختبارات المضيف والجهاز

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

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

// build.gradle.kts

kotlin {
  androidLibrary {
    // ...

    // 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 = "ANDROIDX_TEST_ORCHESTRATOR"
    }
  }
}

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

// 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 = "ANDROIDX_TEST_ORCHESTRATOR"
  }
}

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

‫4- تفعيل تجميع مصدر Java

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

// build.gradle.kts

kotlin {
  androidLibrary {
    //  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

// build.gradle.kts

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

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

5. التفاعل مع صيغ الإنشاء باستخدام androidComponents

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

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

// build.gradle.kts

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

// build.gradle.kts

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

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

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

// build.gradle.kts
kotlin {
  androidLibrary {
    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"))
      }
    }
  }
}

7. التبعيات في إنشاء المعاينة

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

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

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

8. ضبط إصدار JVM المستهدف لنظام التشغيل Android في KMP

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

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

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

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

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

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

    kotlinOptions {
        jvmTarget = "11"
    }
}

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

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

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant