遷移至 Android-KMP 外掛程式

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

先前，將 Android 整合至 KMP 專案的唯一方法，就是使用一般 Android 程式庫 Gradle 外掛程式：com.android.library。不過，這項做法現已淘汰，改用專用的 com.android.kotlin.multiplatform.library 外掛程式，也稱為 Android-KMP 外掛程式。本指南將說明如何遷移至新外掛程式。

主要功能和差異

Android-KMP 外掛程式 (com.android.kotlin.multiplatform.library) 專為 KMP 專案量身打造，在幾個重要方面與傳統 com.android.library 外掛程式不同：

• 單一變化版本架構：外掛程式會使用單一變化版本運作，移除標準 Android 程式庫專案中常見的產品變化版本和建構類型支援，藉此簡化建構程序。這可簡化 KMP Android 程式庫的設定，並提升建構效能。
• 專為 KMP 最佳化：此外掛程式專為 Kotlin Multiplatform 程式庫設計，著重於共用 Kotlin 程式碼和互通性。因此，它會省略對 Android 專屬原生版本、AIDL (Android 介面定義語言) 和 RenderScript 的支援，因為這些通常與 KMP 共用程式碼內容無關。
• 預設停用測試：為進一步提升多平台環境中的建構速度，系統會預設停用測試。如果專案需要，您可以明確啟用測試。這項規定適用於主機上的測試 (單元測試) 和裝置上的測試 (檢測設備測試)。
• 沒有頂層 Android 擴充功能：外掛程式不會在 Gradle 建構檔案中建立頂層 android 擴充功能。設定會透過 Kotlin 多平台 DSL 中的 androidLibrary 區塊處理，以維持一致的 KMP 專案結構。
• 選擇啟用 Java 編譯：系統預設不會啟用 Java 編譯功能。如果您的 KMP 程式庫需要編譯以 Java 為基礎的程式碼，您必須在 kotlin 區塊的 androidLibrary 設定區塊中使用 withJava() API，明確選擇加入編譯。這可讓您更精細地控管編譯程序，並在不需要編譯以 Java 為基礎的程式碼時縮短建構時間。

遷移的好處

Android-KMP 外掛程式可為 KMP 專案提供下列優點：

• 改善建構效能和穩定性：Android-KMP 外掛程式專為在 KMP 專案中提升建構速度和穩定性而設計。其簡化架構和著重於 KMP 工作流程的設計，有助於建構程序更有效率且更可靠。
• 強化 IDE 整合：外掛程式可提供優異的整合功能，與 Android Studio 和其他 Kotlin IDE 整合。這可在使用 KMP Android 程式庫時，提供更優異的程式碼完成、導覽、偵錯和整體開發人員體驗。
• 簡化專案設定：Android-KMP 外掛程式可移除變種版本等 Android 專屬複雜功能，簡化 KMP 專案的設定。這可讓建構檔案更清晰、更易於維護，並縮短 KMP Android 開發新手的學習曲線。先前，當您使用 com.android.library 外掛程式將 Android 整合至 KMP 專案時，多平台結構中 Android Gradle 外掛程式和 Kotlin Gradle 外掛程式之間的互動有時會導致來源集名稱出現誤導。舉例來說，專門用於設定 Android 檢測測試的來源集名稱為 androidAndroidTest。對於熟悉標準 KMP 專案結構的開發人員而言，這個命名慣例不夠直覺。
• 官方建議解決方案：com.android.kotlin.multiplatform.library 外掛程式是使用 com.android.library 外掛程式將 Android 目標新增至 KMP 程式庫的舊版方法的官方替代方案。JetBrains 將不再支援繼續使用 KMP 的 com.android.library 外掛程式，因此您將無法享有日後的更新和改善。

將 Android-KMP 外掛程式套用至專案

將 Android-KMP 外掛程式套用至專案的方法主要有兩種： * 針對現有的 KMP 程式庫模組，請手動編輯 Gradle 檔案。* 如要建立新的 KMP 程式庫模組，請直接在 Android Studio UI 中建立新模組。

將外掛程式套用至現有模組

如要將 Android-KMP 外掛程式套用至現有的 KMP 程式庫模組，請按照下列步驟操作：

1. 開啟版本目錄 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. 在 KMP 程式庫模組的根目錄中開啟 build.gradle.kts (Kotlin) 或 build.gradle (Groovy) 檔案。

3. 在檔案頂端的 plugins 區塊中套用外掛程式：

   Kotlin

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

   Groovy

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

4. 設定 Kotlin Multiplatform 區塊 (kotlin)，定義 Android 目標。在 kotlin 區塊中，使用 androidLibrary 指定 Android 目標：

   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 專案以套用變更。

使用外掛程式建立新模組

您也可以直接在 Android Studio 中建立新的 Kotlin Multiplatform 程式庫模組。系統會自動套用必要的外掛程式，包括 Android-KMP 外掛程式。如需有關如何使用 Android Studio 建立新的 KMP 程式庫模組的進一步指引，請參閱「將 Kotlin Multiplatform 新增至現有專案」。

如要進一步瞭解整體多平台生態系統和更多進階設定，請參閱官方的 Kotlin Multiplatform 說明文件。