開始使用 Kotlin Multiplatform | Android Developers

安裝 XCode

如要建構及執行本程式碼實驗室的 iOS 部分，您需要 Xcode 和 iOS 模擬器：

如果尚未建立 Apple 帳戶，請先完成這項作業。

從 Mac App Store 安裝 Xcode (您需要 Apple 帳戶才能安裝)。

安裝完成後，啟動 Xcode。

系統會顯示對話方塊，指出哪些是內建元件，以及需要下載哪些元件。

確認 iOS 18.4 (或更新版本)。

點選「Download & Install」。

等待元件安裝完成。

注意：Xcode 是大型二進位檔，因此下載及安裝可能需要一段時間。

本程式碼實驗室搭配 Xcode 16.3 進行測試。如果您使用任何其他 Xcode 版本，且遇到問題，建議您下載本程式碼實驗室中所述的確切版本。

範例應用程式

這個程式碼集包含以 Jetpack Compose 建構的 Android 應用程式，以及使用 SwiftUI 建構的 iOS 應用程式。Android 專案位於 androidApp/ 資料夾，而 iOS 專案位於 iosApp/ 資料夾，其中也包含可透過 Xcode 執行的 KMPGetStartedCodelab.xcodeproj。

3. Kotlin Multiplatform 簡介

使用 Kotlin Multiplatform (KMP)，您只需編寫一次程式碼，即可跨多個目標平台 (例如 Android、iOS、網頁和電腦) 共用程式碼。透過 KMP，您可以盡量減少程式碼重複情形、維持一致性，並大幅減少開發時間和工作量。

KMP 不會規定您需要共用程式碼的哪些部分或多少部分。您可以自行決定要共用程式碼的哪些部分。

這個共用程式碼可讓您維持一致性，並減少跨平台的重複情形。許多行動團隊一開始會共用一組獨立的商業邏輯 (例如資料庫存取、網路存取等) 和相關測試，然後隨著時間進展共用其他程式碼。

許多 Android Jetpack 程式庫都支援 KMP。適用於多平台的 Jetpack 程式庫，能讓您根據目標平台提供不同層級的支援。如需完整的程式庫清單及其支援等級，請參閱說明文件。

舉例來說，其中一個支援的程式庫 (Room 資料庫程式庫) 同時支援 Android、iOS 和電腦。這樣一來，您就能將資料庫建立項目和相關資料庫邏輯轉移至通用 KMP 共用模組，同時保留兩個平台上的其他原生程式碼。

遷移資料庫後，您可能會想共用其他網域邏輯。接著，您也可以考慮使用 Android Jetpack 中的 ViewModel 多平台程式庫。

如何編寫平台專屬程式碼

Kotlin Multiplatform 推出了實作平台專屬功能的新技術。

預期和實際宣告

expect actual Kotlin 語言功能旨在支援 Kotlin 多平台程式碼集，並提供完整的 IDE 支援。

如果平台專屬行為可封裝在單一函式或類別中，這個做法就很實用。這是一種靈活且強大的機制。舉例來說，常見的 expect 類別可以有平台專屬的 actual 對應項目，其中包含更開放的可見度修飾符、額外的超級類型，或不同的參數類型或修飾符。嚴格的介面 API 無法提供這些變化版本。此外，expect actual 會以靜態方式解析，這表示系統會在編譯期間強制執行平台專屬的實作項目。

注意：預期/實際類別目前為實驗功能。您也可以實作預期/實際函式的介面。如要瞭解所有選項，請參閱文件。

Kotlin 中的介面與實作項目

如果兩個平台都需要使用類似的 API，但實作方式不同，您可以在共用程式碼中定義介面，做為預期和實際宣告的替代方案。這種做法可讓您使用不同的測試實作方式，或在執行階段切換至其他實作方式。

此外，介面不需要 Kotlin 專屬知識，因此熟悉其他語言介面的開發人員也能輕鬆使用這個選項。

通用共用程式碼中的介面，原生程式碼 (Android 或 Swift) 中的實作項目。

在某些情況下，您需要編寫無法透過 KMP 程式碼提供的程式碼。遇到這種情況，您可以在共用程式碼中定義介面，並在 Kotlin 中為 Android 實作該介面，並在 Swift 中提供 iOS 對應項目。一般來說，原生實作項目會透過依附元件插入或直接插入方式，插入共用程式碼。這項策略可讓您在各個平台上提供自訂體驗，同時保留共用程式碼的通用介面。

將「Project」窗格切換為使用「Project」檢視畫面

在「[root]/iosApp/」資料夾中找出「KmpGetStartedCodelab.xcodeproj」檔案

在檔案上按一下滑鼠右鍵，然後選取「Open In」和「Open in Associated Application」。這樣做會在 Xcode 中開啟 iOS 應用程式。

按一下 ⌘+R 或前往「Product」選單並選取「Run」，即可在 Xcode 中執行專案

注意：您也可以在 Finder 中找出 KmpGetStarted.xcodeproj 檔案，然後按兩下該檔案即可開啟 Xcode 專案，以應用程式的方式啟動。
5. 新增 KMP 模組
如要在專案中新增 KMP 支援功能，請先為跨平台 (Android、iOS) 要重複使用的程式碼建立 shared 模組。

Android Studio 提供一種方法，可使用其 KMP 共用模組範本新增 Kotlin Multiplatform 模組。

如要建立 KMP 模組，請在 Android Studio 中執行下列操作：

依序前往「File」>「New」>「New Module」>「Kotlin Multiplatform Shared Module」

將套件變更為 com.example.kmp.shared

按一下「Finish」

模組建立完成且 Gradle 同步處理完成後，專案中就會顯示新的 shared 模組。要看到下方顯示的檢視畫面，您可能需要從 Android 檢視畫面切換至專案檢視畫面。

KMP 共用模組範本產生的共用模組包含一些基本預留位置函式和測試。這些預留位置可確保模組從一開始就能順利編譯及執行。

重要事項：請留意 iosApp 資料夾和 iosMain 資料夾的差異。iosApp 資料夾包含獨立的 iOS 應用程式程式碼，而 iosMain 則屬於剛才新增的 KMP 共用模組一部分。iosApp 包含 Swift 程式碼，而 iosMain 則包含 iOS 平台專屬的 KMP 程式碼。

將共用模組連結至 Android 應用程式

首先，您必須將新的共用模組連結為 :androidApp Gradle 模組中的依附元件，讓應用程式能使用共用程式碼：

開啟 androidApp/build.gradle.kts 檔案。

如以下所示，在依附元件區塊中新增 shared 模組依附元件

dependencies { implementation(projects.shared) 注意：由於專案已啟用 Gradle 的類型安全專案存取子功能，因此您可以使用 projects.shared. 存取 shared 模組。如果沒有類型安全存取子功能，您可以使用 implementation(project(":shared")) 存取模組。同步處理專案與 Gradle 檔案驗證程式碼對 shared 模組的存取權為了確認 Android 應用程式可以存取 shared 模組中的程式碼，我們會對應用程式進行簡單更新。在 KMPGetStartedCodelab 專案中，開啟 androidApp/src/main/java/com/example/kmp/getstarted/android/MainActivity.kt 中的 MainActivity 檔案修改內容 Text 可組合函式，在顯示的字串中納入 platform() 資訊。 Text( "Hello ${platform()}", 按一下鍵盤上的 ⌥(option)+return，然後選取 Import function 'platform' 在 Android 裝置或模擬器中建構並執行應用程式。這項更新會檢查應用程式是否能從 shared 模組呼叫 platform() 函式，該函式在 Android 平台上執行時應傳回 "Android"。 6. 在 iOS 應用程式中設定共用模組 Swift 無法像 Android 應用程式一樣直接使用 Kotlin 模組，必須產生已編譯的二進位架構 (XCFramework 套件)。XCFramework 套件是二進位檔套件，其中包含多個 Apple 平台建構所需的架構和程式庫。共用程式庫的發布方式 Android Studio 中的新模組範本已設定共用模組，可為每個 iOS 架構產生框架。您可以在 shared 模組的 build.gradle.kts 檔案中找到下列程式碼。 val xcfName = "sharedKit" iosX64 { binaries.framework { baseName = xcfName iosArm64 { binaries.framework { baseName = xcfName iosSimulatorArm64 { binaries.framework { baseName = xcfName 注意：系統預設會根據 KMP 範本 (及以上版本) 中提及的模組名稱，將輸出框架稱為 sharedKit，而這個名稱是由共用模組 build.gradle.kts 檔案中的 xcfName 屬性控制。在您自己的專案中，可以配合框架名稱重新命名，以便定義與框架相關聯的品牌或身分。在 iOS 專案中連結共用程式庫這個步驟包括設定 Xcode 以執行指令碼來產生 Kotlin 框架，以及在 iOS 應用程式中呼叫 platform() 函式。如要使用共用程式庫，您必須按照下列步驟將 Kotlin 框架連結至 iOS 專案：在 Xcode 中開啟 iOS 專案 (先前提到的 iosApp 目錄)，然後在專案導覽器中按兩下專案名稱，開啟專案設定。在專案設定的「Build Phases」分頁標籤中，按一下「+」並選取「New Run Script Phase」。這會在所有其他階段後新增「Run script」階段。按兩下「Run script」標題即可重新命名。將預設的「Run Script」名稱變更為「Compile Kotlin Framework」，讓這個階段所執行的事項一目瞭然。展開建構階段，然後在「Shell」下方的文字欄位中輸入指令碼： cd "$SRCROOT/.." ./gradlew :shared:embedAndSignAppleFrameworkForXcode 將「Compile Kotlin Framework」階段拖曳至「Compile Sources」階段之前。按一下 ⌘+B 或前往「Product」選單，然後選取「Build」，即可在 Xcode 中建構專案。請注意，建構進度會顯示在 Xcode 頂端。注意：如果因為您已針對使用者指令碼採用沙箱機制而發生錯誤，導致建構失敗，請執行下列步驟：在 Xcode 專案中，前往「Build Setting」。在「Build Options」下方，將「User script sandboxing」(ENABLE_USER_SCRIPT_SANDBOXING) 設為 NO。執行 ./gradlew --stop，以在終端機中停止 Gradle Daemon 重建 Xcode 專案如果一切設定正確，專案就會順利建構。透過這種方式設定執行指令碼建構階段，您就能使用 Xcode 編譯 iOS 專案，不需要切換至其他工具來編譯共用模組。注意：如果您變更 shared 程式碼，則必須重新建構專案 (這樣做會觸發 embedAndSignAppleFrameworkForXcode Gradle 工作) 才會在 Xcode 中看到變更。驗證程式碼對 shared 模組的存取權如要確認 iOS 應用程式能成功存取 shared 模組的程式碼，請對應用程式進簡單更新 (與對 Android 應用程式執行的作業相同)。在 iOS 專案的 Xcode 中，開啟 ContentView.swift 檔案：Sources/View/ContentView.swift 在檔案頂端新增 import sharedKit。使用 \(Platform_iosKt.platform()) 修改 Text 檢視畫面，在顯示的字串中加入 Platform_iosKt.platform() 資訊。以下是檔案的最終結果： import SwiftUI import sharedKit struct ContentView: View { var body: some View { VStack { Image(systemName: "globe") .imageScale(.large) .foregroundStyle(.tint) Text("Hello, \(Platform_iosKt.platform())!") .padding() 按一下 ⌘+R 鍵執行應用程式，或前往「Product」選單，然後點選「Run」。注意：建構完成後，您可能會看到警告，指出系統會在每次建構期間執行 Compile Kotlin 指令碼。您可以忽略這則警告。 > 執行指令碼建構階段「Compile Kotlin」會在每次建構期間執行，因為它不會指定任何輸出內容。如要解決這個問題，請在指令碼階段新增輸出依附元件，或是在指令碼階段取消勾選「Based on dependency analysis」，將指令碼設為在每次建構時執行。這項更新會檢查 iOS 應用程式是否能從共用模組呼叫 platform() 函式，該函式應在 iOS 平台上執行時傳回 "iOS"。注意：Swift 中的字串內插類型使用 \(code) 語法。 7. 新增 Swift/Kotlin 介面強化工具 (SKIE) 根據預設，Kotlin 產生的原生介面是 Objective-C 標頭。Swift 可直接與 Objective-C 相容，但 Objective-C 不包含 Swift 或 Kotlin 的所有新功能。這也是在先前範例中，您無法在 Swift 程式碼中直接使用 platform() 呼叫的原因。KMP 無法產生全域函式，因為 Objective-C 只支援類別中封裝的靜態函式，而非全域函式，因此您需要新增 Platform_iosKt。如要讓介面更適合 Swift，您可以使用 Swift/Kotlin Interface Enhancer (SKIE) 工具改善 :shared 模組的 Swift 介面。 SKIE 常見功能如下：更妥善支援預設引數進一步支援封閉階層結構 (sealed class、sealed interface) 提升對 enum class 的支援，使其在 switch 陳述式中具有完整的處理機制 Flow 到 AsyncSequence 之間的互通性 suspend fun 和 async func 之間的互通性提示：雖然在本程式碼實驗室以外的專案中，此步驟是可選步驟，但建議您使用 SKIE，因為這樣可以消除共用框架的許多限制。舉例來說，SKIE 可讓您直接在 Swift 中使用 Kotlin 的 suspend 函式和 Flow 類型，大幅提升 iOS 團隊共用模組的可用性。將 co.touchlab.skie Gradle 外掛程式新增至 libs.versions.toml 檔案： [versions] skie = "0.10.1" [plugins] skie = { id = "co.touchlab.skie", version.ref = "skie" } 將外掛程式新增至根層級 build.gradle.kts 檔案 plugins { alias(libs.plugins.skie) apply false 將外掛程式新增至 :shared 模組 build.gradle.kts 檔案： plugins { alias(libs.plugins.skie) Gradle 同步處理專案注意：SKIE 外掛程式會收集外掛程式使用情形的去識別化分析資料。如要停用此功能，請在 :shared 模組的 build.gradle.kts 檔案中新增 skie.analytics { enabled = false }。詳情請參閱 https://skie.touchlab.co/Analytics**.** 移除靜態函式呼叫重新建構 iOS 應用程式後，您可能不會立即發現任何變化，但可以移除 Platform_iosKt 前置字串，讓 platform() 函式充當全域函式。 Text("Hello, KMP! \(platform())") 這是因為 SKIE (以及其他功能) 會利用 Swift API 附註新增 API 相關資訊，讓 Swift 程式碼進一步使用 API。 8. 恭喜恭喜！您已將第一個共用 Kotlin Multiplatform 程式碼新增至 Android 和 iOS 專案。雖然這只是最基本的起點，但您現在可以開始探索更進階的功能和用途，以便透過 KMP 共用程式碼。在下一個程式碼實驗室中，瞭解如何使用 Jetpack Room 在 Android 和 iOS 之間共用資料層。瞭解哪些 Jetpack 程式庫支援 KMP 參閱官方的 Kotlin Multiplatform 說明文件。 [[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],[],[],[]]