建立跨平台行動應用程式
程式碼範例: tutorial-client-kmp
Ktor HTTP 用戶端可用於多平台專案中。在本教學中,我們將建立一個簡單的 Kotlin Multiplatform Mobile 應用程式,用於傳送請求並以純 HTML 文字形式接收回應主體。
前置準備
首先,您需要透過在合適的作業系統上安裝必要的工具,來設定跨平台行動開發的環境。請參閱設定環境章節了解操作方式。
您將需要一台搭載 macOS 的 Mac 來完成本教學中的特定步驟,包含撰寫 iOS 專用程式碼以及執行 iOS 應用程式。
建立新專案
若要建立新專案,您可以使用 IntelliJ IDEA 中的 Kotlin Multiplatform 專案精靈。它將建立一個基礎的多平台專案,後續您可以為其擴充用戶端與服務。
- 啟動 IntelliJ IDEA。
- 在 IntelliJ IDEA 中,選取 File | New | Project。
- 在左側面板中,選取 Kotlin Multiplatform。
- 在 New Project 視窗中指定以下欄位:
- Name:KmpKtor
- Group:org.example.ktor

- 選取 Gradle 建構系統。
- 選取 Android 與 iOS 目標。
- 針對 iOS,選取 Do not share UI 選項以保留原生 UI。
- 點擊 Create 按鈕,等待 IDE 產生並匯入專案。
設定建置指令碼
新增 Ktor 相依性
若要在專案中使用 Ktor HTTP 用戶端,您至少需要新增兩個相依性:用戶端相依性與引擎相依性。
開啟 settings.gradle.kts 檔案並匯入 Ktor 版本目錄(version catalog):
kotlindependencyResolutionManagement { versionCatalogs { create("ktorLibs").from("io.ktor:ktor-version-catalog:3.6.1") } }開啟 sharedLogic/build.gradle.kts 檔案,並將預設引擎相依性新增至
commonMain原始碼集:kotlinsourceSets { commonMain.dependencies { api(ktorLibs.client.engineDefaults) } }對於每個目標平台,Ktor 會使用由
ktor-client-engine-defaults提供的預設引擎。
新增協同程式
若要在 Android 程式碼中使用協同程式,您需要將 kotlinx.coroutines 新增至專案中:
開啟 gradle/libs.versions.toml 檔案,並指定協同程式版本與程式庫:
toml[versions] kotlinx-coroutines = "1.11.0" [libraries] kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" } kotlinx-coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "kotlinx-coroutines" }開啟 sharedLogic/build.gradle.kts 檔案,並將
kotlinx-coroutines-core相依性新增至commonMain原始碼集:kotlinsourceSets { commonMain.dependencies { api(ktorLibs.client.engineDefaults) implementation(libs.kotlinx.coroutines.core) } }接著,開啟 androidApp/build.gradle.kts 檔案,並將
kotlinx-coroutines-android相依性新增至androidMain原始碼集:kotlindependencies { implementation(libs.kotlinx.coroutines.android) }選取 Build | Sync Project with Gradle Files 以安裝新增的相依性。
更新應用程式
共用程式碼
若要更新 Android 與 iOS 之間共用的程式碼,請開啟 sharedLogic/src/commonMain/kotlin/org/example/ktor/Greeting.kt 檔案,並將以下程式碼新增至 Greeting 類別:
package org.example.ktor
import io.ktor.client.HttpClient
import io.ktor.client.request.get
import io.ktor.client.statement.bodyAsText
class Greeting {
private val client = HttpClient()
suspend fun greet(): String {
val response = client.get("https://ktor.io/docs/")
return response.bodyAsText()
}
}Android 程式碼
開啟 sharedUI/src/commonMain/kotlin/org/example/ktor/App.kt 檔案,並依下列方式更新程式碼:
package org.example.ktor
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.safeContentPadding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.*
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.tooling.preview.Preview
@Composable
@Preview
fun App() {
MaterialTheme {
Column(
modifier = Modifier
.background(MaterialTheme.colorScheme.primaryContainer)
.safeContentPadding()
.fillMaxSize(),
horizontalAlignment = Alignment.CenterHorizontally,
) {
var text by remember { mutableStateOf("Loading") }
LaunchedEffect(true) {
text = try {
Greeting().greet()
} catch (e: Exception) {
e.message ?: "error"
}
}
GreetingView(text)
}
}
}
@Composable
fun GreetingView(text: String) {
Text(text = text)
}
@Preview
@Composable
fun DefaultPreview() {
MaterialTheme {
GreetingView("Hello, Android!")
}
}LaunchedEffect() 會啟動一個與該可組合項(composable)生命週期綁定的協同程式。在此協同程式內,會呼叫共用的 greet() 函式,並將其結果指派給 text,同時擷取並處理任何例外狀況。
iOS 程式碼
開啟 iosApp/iosApp/ContentView.swift 檔案,並依下列方式更新程式碼:
import SharedLogic
import SwiftUI
struct ContentView: View {
@StateObject private var viewModel = ViewModel()
var body: some View {
Text(viewModel.text)
}
}
extension ContentView {
@MainActor
class ViewModel: ObservableObject {
@Published var text = "Loading..."
init() {
Greeting().greet { greeting, error in
if let greeting = greeting {
self.text = greeting
} else {
self.text = error?.localizedDescription ?? "error"
}
}
}
}
}在 iOS 上,greet() suspend 函式會以帶有回呼(callback)的函式形式提供。
在 Android 上啟用網際網路存取
最後一個步驟是為 Android 應用程式啟用網際網路存取權限。 開啟 androidApp/src/main/AndroidManifest.xml 檔案,並使用 <uses-permission> 元素啟用所需的權限:
<manifest>
<uses-permission android:name="android.permission.INTERNET" />
<application>
...
</application>
</manifest>在 Android 上執行應用程式
在 IntelliJ IDEA 中,於執行配置清單中選取 androidApp。
在配置清單旁選取一個 Android 虛擬裝置,然後點擊 Run。

如果清單中沒有裝置,請建立一個新的 Android 虛擬裝置。
載入完成後,模擬器應會將接收到的 HTML 文件顯示為純文字。

如果您的 Android 模擬器無法連線至網際網路,請嘗試執行冷開機(Cold Boot)。 在 Device Manager 工具視窗中,點擊已停止裝置旁的 ⋮(三個點),並從選單中選取 Cold Boot。這通常有助於清除可能導致連線問題的已損毀模擬器快取。
在 iOS 上執行應用程式
在 IntelliJ IDEA 中,於執行配置清單中選取 iosApp。
在配置清單旁選取一個 iOS 模擬裝置,然後點擊 Run。

如果清單中沒有可用的 iOS 設定,請新增一個新的執行配置。
載入完成後,模擬器應會將接收到的 HTML 文件顯示為純文字。

