让 Android 应用程序在 iOS 上运行 – 教程
本教程展示如何将现有的 Android 应用程序改造为跨平台应用,使其能够同时在 Android 和 iOS 上运行。 你将能够在同一个地方一次性为 Android 和 iOS 编写代码。
本教程使用了一个示例 Android 应用程序,其中包含用于输入用户名和密码的单个屏幕。凭据会经过验证并保存到内存数据库中。
为了让你的应用程序能够同时在 iOS 和 Android 上运行, 首先需要将部分代码移至共享模块,以实现跨平台。 之后,你将在 Android 应用程序中使用跨平台代码,并在新的 iOS 应用程序中复用相同的代码。
如果你还不熟悉 Kotlin Multiplatform,请先了解如何从头开始创建跨平台应用程序。
准备开发环境
按照快速入门中的说明,配置用于 Kotlin Multiplatform 开发的环境。
你需要一台搭载 macOS 的 Mac 来完成本教程中的某些步骤(例如运行 iOS 应用程序)。 这是 Apple 的硬性要求。
在 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 中使用该代码。
将业务逻辑代码从
app目录中的com.jetbrains.simplelogin.androidapp.data移动到shared/src/commonMain目录下的com.jetbrains.simplelogin.shared软件包中。
当 Android Studio 询问你想执行什么操作时,选择移动软件包,然后确认重构。

忽略所有关于平台相关代码的警告,点击 Refactor Anyway。

通过将其替换为跨平台 Kotlin 代码,或使用 expect 与 actual 声明连接到 Android 特定 API,从而移除 Android 特定代码。详情请参阅以下部分:
用跨平台代码替换 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类的导入指令: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的导入指令: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 进程可能已被沙箱化,需要重启。 在再次构建项目之前,可以通过在项目目录(在本例中为
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 类代码几乎相同, 如果你的移动应用程序应当具有相同的表现层,你也可以将其共享。
后续步骤
将 Android 应用程序改造为跨平台后,你可以继续探索:
你可以使用 Compose Multiplatform 跨所有平台创建统一的 UI:
你还可以查看社区资源:
