讓你的 Android 應用程式在 iOS 上運作 – 教學
本教學展示如何讓現有的 Android 應用程式實現跨平台,使其能同時在 Android 與 iOS 上運作。 你將能夠在同一個地方同時為 Android 和 iOS 編寫程式碼。
本教學使用一個範例 Android 應用程式,該應用程式包含一個用於輸入使用者名稱和密碼的單一螢幕畫面。憑據經過驗證後會儲存至記憶體資料庫中。
要讓你的應用程式同時在 iOS 和 Android 上運作, 你首先需要將部分程式碼移至共用模組,使其具備跨平台能力。 接著,你將在 Android 應用程式中使用這段跨平台程式碼,然後在新的 iOS 應用程式中重複使用相同的程式碼。
如果你還不熟悉 Kotlin Multiplatform,請先了解如何從頭開始建立跨平台應用程式。
準備開發環境
在快速入門指南中,完成設定 Kotlin Multiplatform 開發環境的說明。
由於 Apple 的硬體限制與要求,你需要一台搭載 macOS 的 Mac 電腦才能完成本教學中的某些步驟,例如執行 iOS 應用程式。
在 Android Studio 中,從版本控制系統建立新專案:
texthttps://github.com/Kotlin/kmp-integration-samplemaster分支包含專案的初始狀態——一個簡單的 Android 應用程式。 若要查看包含 iOS 應用程式和共用模組的最終狀態,請切換至final分支。切換至 Project 檢視:

讓你的程式碼實現跨平台
要使你的程式碼具備跨平台能力,請遵循以下步驟:
決定哪些程式碼要進行跨平台
決定你的 Android 應用程式中哪些程式碼適合與 iOS 共用,哪些程式碼應保留為原生程式碼。一個簡單的原則是: 盡可能共用你想重複使用的部分。商業邏輯在 Android 和 iOS 上通常是相同的, 因此非常適合作為共用復用的候選對象。
在範例 Android 應用程式中,商業邏輯儲存於套件 com.jetbrains.simplelogin.androidapp.data 中。 未來的 iOS 應用程式也將使用相同的邏輯,因此你應該將其改為跨平台程式碼。

為跨平台程式碼建立共用模組
供 iOS 和 Android 共同使用的跨平台程式碼將存儲在共用模組中。 Android Studio 和 IntelliJ IDEA 都提供了建立 Kotlin Multiplatform 共用模組的精靈。
建立一個共用模組,以連接現有的 Android 應用程式和未來的 iOS 應用程式:
在 Android Studio 中,從主選單選擇 File | New | New Module。
在範本清單中,選取 Kotlin Multiplatform Shared Module。 將模組名稱保留為
shared,並輸入套件名稱:textcom.jetbrains.simplelogin.shared點擊 Finish。精靈會建立共用模組、對應地修改組建指令碼,並開始執行 Gradle 同步。
等待同步完成。 你將會在
shared目錄中看到以下檔案結構:
若想更深入了解產生的專案配置結構, 請參閱 Kotlin Multiplatform 專案結構基礎。
將
shared/build.gradle.kts中的kotlin.android {}區塊取代為以下androidLibrary {}區塊, 因為shared模組將作為 Android 應用程式的程式庫使用:kotlinimport org.jetbrains.kotlin.gradle.dsl.JvmTarget kotlin { androidLibrary { namespace = "com.jetbrains.simplelogin.shared" compileSdk = libs.versions.android.compileSdk.get().toInt() compilerOptions { jvmTarget = JvmTarget.JVM_11 } androidResources { enable = true } withHostTestBuilder { } withDeviceTestBuilder { sourceSetTreeName = "test" }.configure { instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" } } //... }
將程式碼新增至共用模組
現在你已經有了共用模組, 在 shared/src/commonMain/kotlin/com.jetbrains.simplelogin.shared 目錄中新增一些要共用的共用程式碼:
建立一個新的
Greeting類別,並加入以下程式碼:kotlinpackage com.jetbrains.simplelogin.shared class Greeting { private val platform = getPlatform() fun greet(): String { return "Hello, ${platform.name}!" } }將現有檔案中的程式碼取代為以下內容:
在
commonMain/Platform.kt中:kotlinpackage com.jetbrains.simplelogin.shared interface Platform { val name: String } expect fun getPlatform(): Platform在
androidMain/Platform.android.kt中:kotlinpackage com.jetbrains.simplelogin.shared import android.os.Build class AndroidPlatform : Platform { override val name: String = "Android ${Build.VERSION.SDK_INT}" } actual fun getPlatform(): Platform = AndroidPlatform()在
iosMain/Platform.ios.kt中:kotlinpackage com.jetbrains.simplelogin.shared import platform.UIKit.UIDevice class IOSPlatform: Platform { override val name: String = UIDevice.currentDevice.systemName() + " " + UIDevice.currentDevice.systemVersion } actual fun getPlatform(): Platform = IOSPlatform()
現在你有了一個通用的 getPlatform() 函式,它會傳回包含平台名稱屬性的平台專用物件。
在你的 Android 應用程式中新增對共用模組的相依性
要在 Android 應用程式中使用跨平台程式碼,請連接共用模組,將商業邏輯程式碼移至該處,並使該程式碼具備跨平台能力。
在
app/build.gradle.kts檔案中新增對共用模組的相依性:kotlindependencies { // ... implementation(project(":shared")) }依照 IDE 的提示同步 Gradle 檔案,或使用選單項目 File | Sync Project with Gradle Files。
在
app/src/main/java/目錄中,開啟com.jetbrains.simplelogin.androidapp.ui.login套件下的LoginActivity.kt檔案。為確保共用模組已成功連接至應用程式,可以在
onCreate()方法中新增Log.i()呼叫,將greet()函式的結果寫入記錄中:kotlinoverride fun onCreate(savedInstanceState: Bundle?) { enableEdgeToEdge() super.onCreate(savedInstanceState) Log.i("Login Activity", "Hello from shared module: " + (Greeting().greet())) // ... }依照 IDE 的提示匯入缺少的類別。
在工具列中,點擊執行設定下拉式選單旁的偵錯圖示:

在 Logcat 工具視窗中,於記錄中搜尋「Hello」,你將會看到來自共用模組的問候訊息:

將商業邏輯改為跨平台
現在你可以將商業邏輯程式碼提取到 Kotlin Multiplatform 共用模組的 commonMain 原始碼集中。 這將允許 Android 和 iOS 同時使用該程式碼。
將商業邏輯程式碼
com.jetbrains.simplelogin.androidapp.data從app目錄移至shared/src/commonMain目錄下的com.jetbrains.simplelogin.shared套件中。
當 Android Studio 詢問你要執行的操作時,選取移動套件並確認重構。

忽略所有關於平台相依程式碼的警告,點擊 Refactor Anyway。

移除 Android 專用程式碼,將其取代為跨平台的 Kotlin 程式碼,或者使用預期宣告與實際宣告 (expected and actual declarations) 連接 Android 專用 API。詳情請參閱以下章節:
將 Android 專用程式碼取代為跨平台程式碼
為了讓程式碼在 Android 和 iOS 上都能順暢運作,請盡可能將移動後的
data目錄中所有的 JVM 相依性取代為 Kotlin 相依性。在
LoginDataValidator類別中,將android.utils套件的Patterns類別替換為符合電子郵件驗證模式的 Kotlin 正規表示式:kotlin// Before private fun isEmailValid(email: String) = Patterns.EMAIL_ADDRESS.matcher(email).matches()kotlin// After private fun isEmailValid(email: String) = emailRegex.matches(email) companion object { private val emailRegex = ("[a-zA-Z0-9\\+\\.\\_\\%\\-\\+]{1,256}" + "\\@" + "[a-zA-Z0-9][a-zA-Z0-9\\-]{0,64}" + "(" + "\\." + "[a-zA-Z0-9][a-zA-Z0-9\\-]{0,25}" + ")+").toRegex() }移除
Patterns類別的 import 指示詞:kotlinimport android.util.Patterns在
LoginDataSource類別中,將login()函式中的IOException取代為RuntimeException。IOException在 Kotlin/JVM 之外的環境不可用。```kotlin // Before return Result.Error(IOException("Error logging in", e)) ``` ```kotlin // After return Result.Error(RuntimeException("Error logging in", e)) ```同時移除
IOException的 import 指示詞:kotlinimport java.io.IOException
實作平台專屬的 UUID 產生機制
在
LoginDataSource類別中,fakeUser的通用唯一識別碼 (UUID) 是使用java.util.UUID類別產生的,但該類別在 iOS 上不可用。kotlinval fakeUser = LoggedInUser(java.util.UUID.randomUUID().toString(), "Jane Doe")雖然 Kotlin 標準庫提供了用於 UUID 產生的類別, 但在此情境中,我們使用平台專屬功能來進行練習。
在共用程式碼中為
randomUUID()函式提供expect宣告,並在相應的原始碼集中為各個平台(Android 與 iOS)提供其actual實作。 你可以進一步了解連接平台專用 API。將
login()函式中的java.util.UUID.randomUUID()呼叫變更為randomUUID()呼叫,你將為每個平台分別實作它:kotlinval fakeUser = LoggedInUser(randomUUID(), "Jane Doe")在
shared/src/commonMain目錄的com.jetbrains.simplelogin.shared套件中建立Utils.kt檔案,並提供expect宣告:kotlinpackage com.jetbrains.simplelogin.shared expect fun randomUUID(): String在
shared/src/androidMain目錄的com.jetbrains.simplelogin.shared套件中建立Utils.android.kt檔案,並提供 Android 的randomUUID()的actual實作:kotlinpackage com.jetbrains.simplelogin.shared import java.util.* actual fun randomUUID() = UUID.randomUUID().toString()在
shared/src/iosMain目錄的com.jetbrains.simplelogin.shared套件中建立Utils.ios.kt檔案,並提供 iOS 的randomUUID()的actual實作:kotlinpackage com.jetbrains.simplelogin.shared import platform.Foundation.NSUUID actual fun randomUUID(): String = NSUUID().UUIDString()在
shared/src/commonMain目錄的LoginDataSource.kt檔案中匯入randomUUID函式:kotlinimport com.jetbrains.simplelogin.shared.randomUUID
現在,Kotlin 將會分別在 Android 和 iOS 上使用各自平台特有的 UUID 實作。
在 Android 上執行你的跨平台應用程式
執行 app 執行配置,以確保 Android 應用程式能像之前一樣正常運作。

讓你的跨平台應用程式在 iOS 上運作
將 Android 應用程式改為跨平台後,你就可以建立 iOS 應用程式並在其中複用共用的商業邏輯。
在 Xcode 中建立 iOS 專案
在 Xcode 中,點擊 File | New | Project。
在對話方塊中,切換至 iOS 標籤頁:

選取 App 範本,然後點擊 Next。
在產品名稱中指定「simpleLoginIOS」,然後點擊 Next。

專案位置請選取存放跨平台應用程式的目錄,例如
kmp-integration-sample。在 Android Studio 中,你將會看到以下結構:

為了與跨平台專案的其他頂層目錄保持一致, 請關閉 Xcode 並將
simpleLoginIOS目錄重新命名為iosApp。如果在開啟 Xcode 的情況下重新命名資料夾,將會收到警告並且可能損壞專案。

設定 iOS 專案以使用 KMP 框架
你可以直接設定 iOS 應用程式與 Kotlin Multiplatform 建置的框架之間的整合。
此方法的替代方案(SwiftPM 與 CocoaPods)已在 iOS 整合方式概覽中介紹。
在 Android Studio 中,右鍵點擊
iosApp/simpleLoginIOS.xcodeproj目錄並選取 Open In | Open In Associated Application,以在 Xcode 中開啟 iOS 專案。在 Xcode 中,點擊 Project 導覽器中的專案名稱以開啟 iOS 專案設定。
在左側的 Targets 區段中選取 simpleLoginIOS,然後點擊 Build Phases 標籤頁。
點擊 + 圖示並選取 New Run Script Phase。

將以下指令碼貼入執行指令碼欄位:
bashif [ "YES" = "$OVERRIDE_KOTLIN_BUILD_IDE_SUPPORTED" ]; then echo "Skipping Gradle build task invocation due to OVERRIDE_KOTLIN_BUILD_IDE_SUPPORTED environment variable set to \"YES\"" exit 0 fi cd "$SRCROOT/.." ./gradlew :shared:embedAndSignAppleFrameworkForXcode停用 Based on dependency analysis 選項。 這可確保 Xcode 在每次組建時都會執行該指令碼,且不會每次都針對遺失的輸出相依項發出警告。

將 Run Script 階段向上移動,放置在 Compile Sources 階段之前:

在 Build Settings 標籤頁中,停用 Build Options 下的 User Script Sandboxing 選項:

如果你有不同於預設
Debug或Release的自訂組建組態,請在 Build Settings 標籤頁的 User-Defined 下新增KOTLIN_FRAMEWORK_BUILD_TYPE設定,並將其設定為Debug或Release。在 Info 標籤頁上,新增自訂屬性
CADisableMinimumFrameDurationOnPhone並將其設為YES, 以在 iOS 上啟用高更新率支援。在 Signing & Capabilities 標籤頁上,選取你的開發團隊,若尚未建立請建立一個。 這可對 KMP 模組產生的
shared框架進行簽署。在此處你還應確保 Bundle Identifier 設定為唯一值,否則 Xcode 可能會導致組建失敗。
在 Xcode 中組建專案(主選單中的 Product | Build)。 如果一切設定正確,專案應該能成功組建 (你可以安全地忽略「build phase will be run during every build」警告)
如果你在停用 User Script Sandboxing 選項之前曾組建專案,組建可能會失敗: Gradle 常駐程式(daemon process)可能已被沙盒化,需要重新啟動。 在再次組建專案之前,請在專案目錄(在我們的範例中為
kmp-integration-sample)中執行以下指令來停止它:shell./gradlew --stop
在 Android Studio 中設定 iOS 執行配置
確認 Xcode 設定無誤後,返回 Android Studio:
在主選單中選取 File | Sync Project with Gradle Files。Android Studio 會自動產生名為 simpleLoginIOS 的執行配置。
Android Studio 會自動產生名為 simpleLoginIOS 的執行配置,並將
iosApp目錄標記為已連結的 Xcode 專案。在執行配置清單中選取 simpleLoginIOS。 選擇一個 iOS 模擬器,然後點擊 Run 以檢查 iOS 執行配置是否能正常運作。

在 iOS 專案中使用共用模組
shared/build.gradle.kts 檔案為每個 iOS 目標將 binaries.framework.baseName 屬性定義為 sharedKit。 這是 Kotlin Multiplatform 建置給 iOS 應用程式使用的框架名稱。
若要測試整合情況,請在 Swift 程式碼中新增對共用程式碼的呼叫:
在 Android Studio 中,開啟
iosApp/simpleloginIOS/ContentView.swift檔案並匯入該框架:swiftimport sharedKit為檢查是否已正確連接,請更新
ContentView結構的程式碼,以使用來自shared模組的greet()函式:swiftstruct ContentView: View { var body: some View { Text(Greeting().greet()) .padding() } }使用 Android Studio 的 iOS 執行配置執行應用程式以查看結果:

再次更新
ContentView.swift檔案中的程式碼,使用共用模組中的商業邏輯來呈現應用程式 UI:kotlin在
simpleLoginIOSApp.swift檔案中,匯入sharedKit模組並指定ContentView()函式的引數:swiftimport SwiftUI import sharedKit @main struct SimpleLoginIOSApp: App { var body: some Scene { WindowGroup { ContentView(viewModel: .init(loginRepository: LoginRepository(dataSource: LoginDataSource()), loginValidator: LoginDataValidator())) } } }再次執行 iOS 執行配置,確認 iOS 應用程式顯示了登入表單。
輸入「Jane」作為使用者名稱,輸入「password」作為密碼。
由於你先前已設定好整合, iOS 應用程式會使用共用程式碼來驗證輸入內容:

享受成果 – 僅需更新一次邏輯
現在你的應用程式已經實現跨平台。你可以在 shared 模組中更新商業邏輯,並同時在 Android 和 iOS 上查看成果。
修改使用者密碼的驗證邏輯:「password」不應是合法的密碼選項。 若要進行修改,請更新
LoginDataValidator類別的checkPassword()函式 (要快速找到它,請按兩下 Shift 鍵,貼上類別名稱,然後切換至 Classes 標籤頁):kotlinpackage com.jetbrains.simplelogin.shared.data class LoginDataValidator { //... fun checkPassword(password: String): Result { return when { password.length < 5 -> Result.Error("Password must be >5 characters") password.lowercase() == "password" -> Result.Error("Password shouldn't be \"password\"") else -> Result.Success } } //... }從 Android Studio 中分別執行 iOS 和 Android 應用程式以查看變更 (在 iOS 上點擊紅色警告三角形時會顯示錯誤訊息):

你可以檢視本教學的最終程式碼。
還有什麼可以共用?
你已經共用了應用程式的商業邏輯,但你也可以決定共用應用程式的其他層級。 例如,Android 和 iOS 應用程式中的 ViewModel 類別程式碼幾乎相同, 如果你的行動應用程式需要擁有相同的展示層(presentation layer),你也可以將其共用。
後續步驟
將 Android 應用程式實現跨平台後,你可以繼續進行以下操作:
你可以使用 Compose Multiplatform 在所有平台上建立統一的 UI:
你也可以參考社群資源:
