使用 Ktor 和 SQLDelight 建立多平台應用程式
本教學使用 IntelliJ IDEA,但你也可以在 Android Studio 中進行——這兩款 IDE 擁有相同的核心功能與 Kotlin Multiplatform 支援。
本教學示範如何使用 IntelliJ IDEA 透過 Kotlin Multiplatform 建立適用於 iOS 和 Android 的進階行動應用程式。 此應用程式將會:
- 使用 Ktor 和
kotlinx.serialization透過網際網路從公開的 Launch Library 擷取資料。 - 使用 SQLDelight 將資料儲存至本機資料庫中。
- 顯示太空火箭發射清單,包含發射日期、結果以及發射的詳細描述。
- 使用 Koin 提供平台專屬的資料庫驅動程式。
該應用程式將包含一個具有 iOS 和 Android 平台共享程式碼的模組。商業邏輯與資料存取層僅需在共享模組中實作一次,而這兩個應用程式的 UI 則皆為原生。

建立專案
在快速入門中,完成設定 Kotlin Multiplatform 開發環境的說明。
在 IntelliJ IDEA 中,選取 File | New | Project。
在左側面板中,選取 Kotlin Multiplatform(在 Android Studio 中,該範本可在 New Project 精靈的 Generic 標籤頁中找到)。
在 New Project 視窗中指定以下欄位:
- Name:SpaceTutorial
- Project ID:com.jetbrains.spacetutorial
選取 Android 與 iOS 目標。
對於 iOS,選取 Do not share UI 選項。你將為這兩個平台實作原生 UI。
指定所有欄位和目標後,點擊 Create。

新增 Gradle 相依性
若要將多平台程式庫新增至共享模組,請在該模組的 build.gradle.kts 檔案中,將相依性指令(implementation)新增至相應原始碼集的 dependencies {} 區塊中。
kotlinx.serialization 和 SQLDelight 程式庫也需要額外配置。
在 gradle/libs.versions.toml 檔案的版本目錄(version catalog)中修改或新增行,以反映所有必要的相依性:
在
[versions]區塊中,檢查 AGP 版本並新增其餘內容:[versions] {...}
toml[versions] agp = "9.0.1" material3 = "1.11.0-alpha07" # ... coroutinesVersion = "1.11.0" dateTimeVersion = "0.8.0" koin = "4.2.2" ktor = "3.5.2" sqlDelight = "2.3.2"在
[libraries]區塊中,新增以下程式庫參照:[libraries] {...}
[libraries] ... koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" } koin-androidx-compose = { module = "io.insert-koin:koin-androidx-compose", version.ref = "koin" } kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutinesVersion" } kotlinx-datetime = { module = "org.jetbrains.kotlinx:kotlinx-datetime", version.ref = "dateTimeVersion" } ktor-client-android = { module = "io.ktor:ktor-client-android", version.ref = "ktor" } ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" } ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" } ktor-client-darwin = { module = "io.ktor:ktor-client-darwin", version.ref = "ktor" } ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" } sqldelight-android-driver = { module = "app.cash.sqldelight:android-driver", version.ref = "sqlDelight" } sqldelight-native-driver = { module = "app.cash.sqldelight:native-driver", version.ref = "sqlDelight" } sqldelight-runtime = { module = "app.cash.sqldelight:runtime", version.ref = "sqlDelight" }在
[plugins]區塊中,指定必要的 Gradle 外掛程式:toml[plugins] # ... kotlinxSerialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" } sqldelight = { id = "app.cash.sqldelight", version.ref = "sqlDelight" }版本目錄更新後,系統會提示你重新同步專案。 點擊 Sync Gradle Changes 按鈕以同步 Gradle 檔案:

在
sharedLogic/build.gradle.kts檔案的最開頭,將以下行新增至plugins {}區塊:kotlinplugins { // ... alias(libs.plugins.kotlinxSerialization) alias(libs.plugins.sqldelight) }common 原始碼集需要各個程式庫的核心產物,以及使用
kotlinx.serialization所需的 Ktor 序列化功能。 iOS 和 Android 原始碼集也需要 SQLDelight 與 Ktor 的平台驅動程式。在同一個
sharedLogic/build.gradle.kts檔案中,新增所有必要的相依性:kotlinkotlin { // ... sourceSets { commonMain.dependencies { implementation(libs.kotlinx.coroutines.core) implementation(libs.ktor.client.core) implementation(libs.ktor.client.content.negotiation) implementation(libs.ktor.serialization.kotlinx.json) implementation(libs.sqldelight.runtime) implementation(libs.kotlinx.datetime) implementation(libs.koin.core) } androidMain.dependencies { implementation(libs.ktor.client.android) implementation(libs.sqldelight.android.driver) } iosMain.dependencies { implementation(libs.ktor.client.darwin) implementation(libs.sqldelight.native.driver) } } }指定相依性後,再次點擊 Sync Gradle Changes 按鈕以更新 Gradle 檔案。
完成 Gradle 同步後,即完成了專案配置,可以開始編寫程式碼。
若需多平台相依性的深入指南,請參閱對 Kotlin Multiplatform 程式庫的相依性。
建立應用程式資料模型
教學中的應用程式將包含公開的 SpaceSDK 類別,作為網路與快取服務的門面(facade)。 應用程式資料模型將有三個實體類別,包含:
- 關於發射的一般資訊
- 任務徽章圖片的連結
- 與發射相關的文章 URL
在本教學結束時,並非所有這些資料都會顯示在 UI 中。 我們使用此資料模型來展示序列化。 但你可以隨意運用連結與徽章,將此範例擴展為更豐富的內容!
建立必要的資料類別:
在
sharedLogic/src/commonMain/kotlin/com/jetbrains/spacetutorial目錄中建立entity套件,然後在該套件內建立Entity.kt檔案。宣告基本實體的所有資料類別:
kotlin
每個可序列化的類別都必須使用 @Serializable 註解標記。kotlinx.serialization 外掛程式會自動為 @Serializable 類別產生預設序列化器,除非你在註解引數中明確傳入序列化器的參照。
@SerialName 註解可讓你重新定義欄位名稱,這有助於使用更具可讀性的識別符號來存取資料類別中的屬性。
配置 SQLDelight 並實作快取邏輯
SQLDelight 程式庫可讓你從 SQL 查詢產生型別安全的 Kotlin 資料庫 API。在編譯期間,產生器會驗證 SQL 查詢,並將其轉換為可在共享模組中使用的 Kotlin 程式碼。
配置 SQLDelight
專案中已包含 SQLDelight 相依性。 若要配置該程式庫,請開啟 sharedLogic/build.gradle.kts 檔案,並在末尾新增 sqldelight {} 區塊。 此區塊包含資料庫清單及其參數:
sqldelight {
databases {
create("AppDatabase") {
packageName.set("com.jetbrains.spacetutorial.cache")
}
}
}packageName 參數保存產生的 Kotlin 原始碼的套件名稱。
出現提示時同步 Gradle 專案檔案,或按兩下 Shift 鍵並搜尋 Sync All Gradle, Swift Package Manager projects 操作。
建議安裝官方的 SQLDelight 外掛程式以處理 .sq 檔案。
產生資料庫 API
首先,建立包含所有必要 SQL 查詢的 .sq 檔案。預設情況下,SQLDelight 外掛程式會在原始碼集的 sqldelight 資料夾中尋找 .sq 檔案:
在
sharedLogic/src/commonMain目錄中,建立新的sqldelight目錄。在
sqldelight目錄中,建立名稱為com/jetbrains/spacetutorial/cache的新目錄,以建立套件的巢狀目錄。在
cache目錄內,建立AppDatabase.sq檔案(名稱與你在build.gradle.kts檔案中指定的資料庫名稱相同)。 你的應用程式的所有 SQL 查詢都將儲存在此檔案中。資料庫將包含一個存有發射相關資料的資料表。 將以下程式碼新增至
AppDatabase.sq檔案以建立資料表,並定義稍後將使用的幾個函式:sqlimport kotlin.Boolean; CREATE TABLE Launch ( flightNumber TEXT NOT NULL, missionName TEXT NOT NULL, launchDateUTC TEXT NOT NULL, imageSmall TEXT NOT NULL, imageLarge TEXT NOT NULL, statusId INTEGER NOT NULL, statusName TEXT NOT NULL, statusDescription TEXT NOT NULL ); insertLaunch: INSERT INTO Launch(flightNumber, missionName, launchDateUTC, imageSmall, imageLarge, statusId, statusName, statusDescription) VALUES(?, ?, ?, ?, ?, ?, ?, ?); removeAllLaunches: DELETE FROM Launch; selectAllLaunchesInfo: SELECT Launch.* FROM Launch;產生對應的
AppDatabase介面(稍後你將使用資料庫驅動程式將其初始化)。 為此,請在專案根目錄的終端中執行以下指令:shell./gradlew generateCommonMainAppDatabaseInterface產生的 Kotlin 程式碼儲存在
sharedLogic/build/generated/sqldelight目錄中。
建立平台專屬資料庫驅動程式的工廠
若要初始化 AppDatabase 介面,你需要將 SqlDriver 執行個體傳遞給它。 SQLDelight 提供了 SQLite 驅動程式的多種平台專屬實作,因此你需要為每個平台分別建立這些執行個體。
雖然你可以透過 expected 和 actual 介面來實現這一點, 但在本專案中,你將使用 Koin 來嘗試 Kotlin Multiplatform 中的相依注入。
建立資料庫驅動程式的介面。為此,請在
sharedLogic/src/commonMain/kotlin/com/jetbrains/spacetutorial/目錄中建立cache套件。在
cache套件內建立DatabaseDriverFactory介面:kotlinpackage com.jetbrains.spacetutorial.cache import app.cash.sqldelight.db.SqlDriver interface DatabaseDriverFactory { fun createDriver(): SqlDriver }建立為 Android 實作此介面的類別:在
sharedLogic/src/androidMain/kotlin目錄中建立com.jetbrains.spacetutorial.cache套件,然後在其中建立AndroidDatabaseDriverFactory.kt檔案。在 Android 上,SQLite 驅動程式由
AndroidSqliteDriver類別實作。在DatabaseDriverFactory.kt檔案中,將資料庫資訊與 context 參照傳遞給AndroidSqliteDriver類別建構函式:kotlinpackage com.jetbrains.spacetutorial.cache import android.content.Context import app.cash.sqldelight.db.SqlDriver import app.cash.sqldelight.driver.android.AndroidSqliteDriver class AndroidDatabaseDriverFactory(private val context: Context) : DatabaseDriverFactory { override fun createDriver(): SqlDriver { return AndroidSqliteDriver(AppDatabase.Schema, context, "launch.db") } }對於 iOS,在
shared/src/iosMain/kotlin/com/jetbrains/spacetutorial/目錄中建立cache套件。在
cache套件內,建立DatabaseDriverFactory.kt檔案並新增以下程式碼:kotlinpackage com.jetbrains.spacetutorial.cache import app.cash.sqldelight.db.SqlDriver import app.cash.sqldelight.driver.native.NativeSqliteDriver class IOSDatabaseDriverFactory : DatabaseDriverFactory { override fun createDriver(): SqlDriver { return NativeSqliteDriver(AppDatabase.Schema, "launch.db") } }
稍後你將在專案的平台專屬部分中使用這些工廠。
實作快取
到目前為止,你已新增了平台資料庫驅動程式的工廠以及用於執行資料庫操作的 AppDatabase 介面。 現在,建立一個 Database 類別,它將封裝 AppDatabase 介面並包含快取邏輯。
在 common 原始碼集
sharedLogic/src/commonMain/kotlin中的com.jetbrains.spacetutorial.cache套件內建立一個新的Database類別。它將包含兩個平台通用的邏輯。若要為
AppDatabase提供驅動程式,請將抽象的DatabaseDriverFactory執行個體傳遞給Database類別建構函式:kotlinpackage com.jetbrains.spacetutorial.cache internal class Database(databaseDriverFactory: DatabaseDriverFactory) { private val database = AppDatabase(databaseDriverFactory.createDriver()) private val dbQuery = database.appDatabaseQueries }此類別的可見性設定為 internal,這表示它只能在多平台模組內部存取。
在
Database類別內部實作一些資料處理操作。 首先,建立getAllLaunches()函式以傳回所有火箭發射的清單。mapLaunchSelecting()函式用於將資料庫查詢的結果對應為RocketLaunch物件:internal fun getAllLaunches() {...}
kotlinimport com.jetbrains.spacetutorial.entity.Image import com.jetbrains.spacetutorial.entity.LaunchStatus import com.jetbrains.spacetutorial.entity.RocketLaunch internal class Database(databaseDriverFactory: DatabaseDriverFactory) { private val database = AppDatabase(databaseDriverFactory.createDriver()) private val dbQuery = database.appDatabaseQueries internal fun getAllLaunches(): List<RocketLaunch> { return dbQuery.selectAllLaunchesInfo(::mapLaunchSelecting).executeAsList() } private fun mapLaunchSelecting( flightNumber: String, missionName: String, launchDateUTC: String, imageSmall: String, imageLarge: String, statusId: Long, statusName: String, statusDescription: String ): RocketLaunch { return RocketLaunch( id = flightNumber, missionName = missionName, launchDateUTC = launchDateUTC, image = Image( small = imageSmall, large = imageLarge ), status = LaunchStatus( id = statusId.toInt(), name = statusName, description = statusDescription ) ) } }新增
clearAndCreateLaunches()函式以清除資料庫並插入新資料:kotlininternal class Database(databaseDriverFactory: DatabaseDriverFactory) { // ... internal fun clearAndCreateLaunches(launches: List<RocketLaunch>) { dbQuery.transaction { dbQuery.removeAllLaunches() launches.forEach { launch -> dbQuery.insertLaunch( flightNumber = launch.id, missionName = launch.missionName, launchDateUTC = launchDateUTC, imageSmall = launch.image.small, imageLarge = launch.image.large, statusId = launch.status.id.toLong(), statusName = launch.status.name, statusDescription = launch.status.description, ) } } } }
實作 API 服務
若要透過網際網路擷取資料,你將使用 Launch Library 公開 API,以及一個從 /2.3.0/launches 端點擷取所有發射清單的方法。
建立一個將應用程式連線至該 API 的類別:
在
sharedLogic/src/commonMain/kotlin/com/jetbrains/spacetutorial/目錄中建立network套件。在
network目錄內建立SpaceApi類別:kotlinpackage com.jetbrains.spacetutorial.network import io.ktor.client.HttpClient import io.ktor.client.plugins.contentnegotiation.ContentNegotiation import io.ktor.serialization.kotlinx.json.json import kotlinx.serialization.json.Json class SpaceApi { private val httpClient = HttpClient { install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true useAlternativeNames = false }) } } }此類別負責執行網路請求,並將 JSON 回應反序列化為
com.jetbrains.spacetutorial.entity套件中的實體。 Ktor 的HttpClient執行個體初始化並儲存httpClient屬性。此程式碼使用
ContentNegotiationKtor 外掛程式來反序列化GET請求的結果。該外掛程式將請求與回應酬載處理為 JSON,並依需求進行序列化與反序列化。宣告傳回火箭發射清單的資料擷取函式:
kotlinimport com.jetbrains.spacetutorial.entity.RocketLaunch import com.jetbrains.spacetutorial.entity.LaunchListResponse import io.ktor.client.request.get import io.ktor.client.call.body class SpaceApi { // ... suspend fun getAllLaunches(): List<RocketLaunch> { return (httpClient.get("https://lldev.thespacedevs.com/2.3.0/launches/previous/?mode=list&format=json").body() as LaunchListResponse).results } }
getAllLaunches 函式具有 suspend 修飾詞,因為它包含對掛起函式 HttpClient.get() 的呼叫。 HttpClient.get() 函式包含透過網際網路擷取資料的非同步操作,且只能從協同程式或其他掛起函式中呼叫。網路請求將在 HTTP 用戶端的執行緒池中執行。
用於傳送 GET 請求的 URL 作為引數傳遞給 get() 函式。
建置 SDK
你的 iOS 與 Android 應用程式將透過共享模組與太空 API 進行通訊,該模組將提供一個公開類別 SpaceSDK。
在 common 原始碼集
sharedLogic/src/commonMain/kotlin的com.jetbrains.spacetutorial套件中建立SpaceSDK類別。 此類別將作為Database和SpaceApi類別的門面。若要建立
Database類別執行個體,請提供DatabaseDriverFactory執行個體:kotlinpackage com.jetbrains.spacetutorial import com.jetbrains.spacetutorial.cache.Database import com.jetbrains.spacetutorial.cache.DatabaseDriverFactory import com.jetbrains.spacetutorial.network.SpaceApi class SpaceSDK(databaseDriverFactory: DatabaseDriverFactory, val api: SpaceApi) { private val database = Database(databaseDriverFactory) }你將在平台專屬程式碼中透過
SpaceSDK類別建構函式注入正確的資料庫驅動程式。新增
getLaunches函式,它使用建立的資料庫與 API 來請求並儲存發射清單:kotlinimport com.jetbrains.spacetutorial.entity.RocketLaunch class SpaceSDK(databaseDriverFactory: DatabaseDriverFactory, val api: SpaceApi) { // ... @Throws(Exception::class) suspend fun getLaunches(forceReload: Boolean): List<RocketLaunch> { val cachedLaunches = database.getAllLaunches() return if (cachedLaunches.isNotEmpty() && !forceReload) { cachedLaunches } else { api.getAllLaunches().also { database.clearAndCreateLaunches(it) } } } }
該類別包含一個用於取得所有發射資訊的函式。根據 forceReload 的值,它會傳回快取值,或從網際網路載入資料並用結果更新快取。如果沒有快取資料,無論 forceReload 旗標的值為何,它都會從網際網路載入資料。
你 SDK 的用戶端可以使用 forceReload 旗標來載入關於發射的最新資訊,從而為使用者實現下拉重新整理(pull-to-refresh)手勢。
Kotlin 的所有例外皆為非受檢例外,而 Swift 只有受檢錯誤(詳見與 Swift/Objective-C 的互通性)。因此,為了讓 Swift 程式碼察覺預期的例外,從 Swift 呼叫的 Kotlin 函式應使用 @Throws 註解標記,並指定潛在的例外類別清單。
建立 Android 應用程式
IntelliJ IDEA 會為你處理初始 Gradle 配置,因此 sharedUI 和 sharedLogic 模組已經連線至你的 Android 應用程式(androidApp)。
出現提示時同步 Gradle 專案檔案,或按兩下 Shift 鍵並搜尋 Sync All Gradle, Swift Package Manager projects。
為 androidApp 新增網際網路存取權限
若要存取網際網路,Android 應用程式需要適當的權限。 在 androidApp/src/main/AndroidManifest.xml 檔案中,新增 <uses-permission> 標籤:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.INTERNET" />
<!--...-->
</manifest>新增相依注入程式碼
Koin 相依注入可讓你宣告可在不同環境中使用的模組(元件集合)。 在此專案中,你將建立兩個模組:一個用於 Android 應用程式,另一個用於 iOS 應用程式。 然後,你將使用相應的模組為各個原生 UI 啟動 Koin。
宣告一個包含 Android 應用程式元件的 Koin 模組:
將
androidMain原始碼集的 Koin Android 相依性新增至sharedUI/build.gradle.kts檔案:kotlinkotlin { // ... sourceSets { androidMain.dependencies { // ... implementation(libs.koin.androidx.compose) } } }建立
sharedUI/src/androidMain/kotlin目錄以存放 Android 專屬的 UI 程式碼。在
sharedUI/src/androidMain/kotlin目錄中,建立com.jetbrains.spacetutorial套件。從
sharedUI模組中移除commonMain和commonTest原始碼集,因為 Android UI 並未共享。在
sharedUI/src/androidMain/kotlin/com.jetbrains.spacetutorial套件中建立AppModule.kt檔案。在該檔案中,將 Koin 模組宣告為兩個單例,一個用於
SpaceApi類別,另一個用於SpaceSDK類別:kotlinimport com.jetbrains.spacetutorial.cache.AndroidDatabaseDriverFactory import com.jetbrains.spacetutorial.network.SpaceApi import org.koin.android.ext.koin.androidContext import org.koin.dsl.module val appModule = module { single<SpaceApi> { SpaceApi() } single<SpaceSDK> { SpaceSDK( databaseDriverFactory = AndroidDatabaseDriverFactory(androidContext()), api = get() ) } }SpaceSDK類別建構函式注入了平台專屬的AndroidDatabaseDriverFactory類別。get()函式解析模組內的相依性:在SpaceSDK()的api參數位置,Koin 會傳入稍早宣告的SpaceApi單例。在
androidApp/build.gradle.kts檔案中,為androidApp模組新增 Koin Android 相依性:kotlinkotlin { // ... dependencies { // ... implementation(libs.koin.androidx.compose) } }在
androidApp模組的src/main/kotlin/com/jetbrains/spacetutorial目錄中建立MainApplication類別,它將啟動 Koin 模組。將你在
AppModule.kt檔案中宣告的模組傳遞給modules()函式:kotlinpackage com.jetbrains.spacetutorial import android.app.Application import org.koin.android.ext.koin.androidContext import org.koin.core.context.GlobalContext.startKoin class MainApplication : Application() { override fun onCreate() { super.onCreate() startKoin { androidContext(this@MainApplication) modules(appModule) } } }在
AndroidManifest.xml檔案的<application>標籤中指定你建立的MainApplication類別:xml<manifest xmlns:android="http://schemas.android.com/apk/res/android"> ... <application ... android:name="com.jetbrains.spacetutorial.MainApplication"> ... </application> </manifest>
現在,你已準備好實作 UI,該 UI 將使用平台專屬資料庫驅動程式提供的資訊。
準備包含發射清單的 ViewModel
你將使用 Jetpack Compose 和 Material 3 實作 Android UI。首先,你將建立使用 SDK 取得發射清單的 ViewModel。接著設定 Material 主題,最後編寫將這一切整合在一起的 Composable 函式。
在
sharedUI/src/androidMain/kotlin目錄下的com.jetbrains.spacetutorial套件中,建立RocketLaunchViewModel.kt檔案:kotlinpackage com.jetbrains.spacetutorial import androidx.compose.runtime.State import androidx.compose.runtime.mutableStateOf import androidx.lifecycle.ViewModel import com.jetbrains.spacetutorial.entity.RocketLaunch class RocketLaunchViewModel(private val sdk: SpaceSDK) : ViewModel() { private val _state = mutableStateOf(RocketLaunchScreenState()) val state: State<RocketLaunchScreenState> = _state } data class RocketLaunchScreenState( val isLoading: Boolean = false, val launches: List<RocketLaunch> = emptyList() )RocketLaunchScreenState執行個體將儲存從 SDK 接收到的資料以及請求的目前狀態。將
loadLaunches函式新增至RocketLaunchViewModel類別中,該函式將在此 ViewModel 的協同程式作用域中呼叫 SDK 的getLaunches函式:kotlinimport androidx.lifecycle.viewModelScope import kotlinx.coroutines.launch class RocketLaunchViewModel(private val sdk: SpaceSDK) : ViewModel() { //... fun loadLaunches() { viewModelScope.launch { _state.value = _state.value.copy(isLoading = true, launches = emptyList()) try { val launches = sdk.getLaunches(forceReload = true) _state.value = _state.value.copy(isLoading = false, launches = launches) } catch (_: Exception) { _state.value = _state.value.copy(isLoading = false, launches = emptyList()) } } } }在
RocketLaunchViewModel類別內部新增帶有loadLaunches()呼叫的init {}區塊,以便在建立RocketLaunchViewModel物件時立即從 API 請求資料:kotlinclass RocketLaunchViewModel(private val sdk: SpaceSDK) : ViewModel() { // ... init { loadLaunches() } }現在,在
AppModule.kt檔案中,於 Koin 模組內指定 ViewModel:kotlinimport org.koin.core.module.dsl.viewModel val appModule = module { // ... viewModel { RocketLaunchViewModel(sdk = get()) } }
建置 Material 主題
你將圍繞 Material 主題提供的 AppTheme 函式建構主 App() Composable:
你可以使用 Material Theme Builder 為你的 Compose 應用程式產生主題。 挑選顏色、字型,然後點擊右下角的 Export theme。
在匯出畫面中,點擊 Export 下拉式功能表,然後選取 Jetpack Compose (Theme.kt) 選項。
解包壓縮檔並將
theme資料夾複製到sharedUI/src/androidMain/kotlin/com/jetbrains/spacetutorial目錄中:
在
theme套件內的每個檔案中,修改package行以參照你建立的套件:kotlinpackage com.jetbrains.spacetutorial.theme在
Color.kt檔案中,為成功與不成功的發射新增兩個即將使用的顏色變數:kotlinval app_theme_successful = Color(0xff4BB543) val app_theme_unsuccessful = Color(0xffFC100D)
實作展示邏輯
為你的應用程式建立主要的 App() Composable,並從 ComponentActivity 類別中呼叫它:
在
sharedUI/src/androidApp/kotlin/com/jetbrains/spacetutorial目錄中建立App.kt檔案。開啟
App.kt檔案並插入以下程式碼:kotlinpackage com.jetbrains.spacetutorial import androidx.compose.material3.pulltorefresh.rememberPullToRefreshState import androidx.compose.runtime.Composable import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.remember import androidx.compose.runtime.rememberCoroutineScope import androidx.compose.runtime.setValue import androidx.compose.ui.tooling.preview.Preview import org.koin.androidx.compose.koinViewModel import androidx.compose.material3.ExperimentalMaterial3Api @OptIn( ExperimentalMaterial3Api::class ) @Composable @Preview fun App() { val viewModel = koinViewModel<RocketLaunchViewModel>() val state by remember { viewModel.state } val coroutineScope = rememberCoroutineScope() var isRefreshing by remember { mutableStateOf(false) } val pullToRefreshState = rememberPullToRefreshState() }在這裡,你使用 Koin ViewModel API 來參照你在 Android Koin 模組中宣告的
viewModel。現在新增 UI 程式碼,以實作載入畫面、發射結果欄位以及下拉重新整理操作:
import com.jetbrains.spacetutorial.theme.AppTheme {...}
kotlinimport androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.fillMaxSize import androidx.compose.foundation.layout.padding import androidx.compose.foundation.lazy.LazyColumn import androidx.compose.foundation.lazy.items import androidx.compose.material3.* import androidx.compose.material3.pulltorefresh.PullToRefreshBox import androidx.compose.material3.pulltorefresh.rememberPullToRefreshState import androidx.compose.runtime.* import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.tooling.preview.Preview import androidx.compose.ui.unit.dp import com.jetbrains.spacetutorial.entity.RocketLaunch import com.jetbrains.spacetutorial.theme.AppTheme import com.jetbrains.spacetutorial.theme.app_theme_successful import com.jetbrains.spacetutorial.theme.app_theme_unsuccessful import kotlinx.coroutines.launch import org.koin.androidx.compose.koinViewModel @OptIn(ExperimentalMaterial3Api::class) @Composable @Preview fun App() { val viewModel = koinViewModel<RocketLaunchViewModel>() val state by remember { viewModel.state } val coroutineScope = rememberCoroutineScope() var isRefreshing by remember { mutableStateOf(false) } val pullToRefreshState = rememberPullToRefreshState() AppTheme { Scaffold( topBar = { TopAppBar( title = { Text( "Space Launches", style = MaterialTheme.typography.headlineLarge ) } ) } ) { padding -> PullToRefreshBox( modifier = Modifier .fillMaxSize() .padding(padding), state = pullToRefreshState, isRefreshing = isRefreshing, onRefresh = { isRefreshing = true coroutineScope.launch { viewModel.loadLaunches() isRefreshing = false } } ) { if (state.isLoading && !isRefreshing) { Column( verticalArrangement = Arrangement.Center, horizontalAlignment = Alignment.CenterHorizontally, modifier = Modifier.fillMaxSize() ) { Text("Loading...", style = MaterialTheme.typography.bodyLarge) } } else { LazyColumn { items(state.launches) { launch: RocketLaunch -> Column( verticalArrangement = Arrangement.spacedBy(8.dp), modifier = Modifier.padding(16.dp) ) { Text( text = launch.missionName, style = MaterialTheme.typography.headlineSmall ) Text( text = if (launch.status.id == 3) "Successful" else "Unsuccessful", color = if (launch.status.id == 3) app_theme_successful else app_theme_unsuccessful ) Text( text = "Launch year: ${launch.launchYear}" ) val details = launch.status.description if (details.isNotBlank()) { Text(details) } } HorizontalDivider() } } } } } } }最後,在
androidApp/src/main/AndroidManifest.xml的<activity>標籤中指定你的MainActivity類別:xml<manifest xmlns:android="http://schemas.android.com/apk/res/android"> ... <application ... <activity ... android:name="com.jetbrains.spacetutorial.MainActivity"> ... </activity> </application> </manifest>執行你的 Android 應用程式:從執行設定功能表中選取 androidApp,選擇一個模擬器,然後點擊執行按鈕。 應用程式會自動執行 API 請求並顯示發射清單(背景顏色取決於你產生的 Material 主題):

你剛剛建立了一個 Android 應用程式,其商業邏輯在 Kotlin Multiplatform 模組中實作,而 UI 則在原生 Jetpack Compose 上運行。
建立 iOS 應用程式
對於專案的 iOS 部分,你將使用 SwiftUI 來建構使用者介面,並採用 Model View View-Model 模式。
IntelliJ IDEA 會產生一個已連線至共享模組的 iOS 專案。Kotlin 模組會以 sharedLogic/build.gradle.kts 檔案中指定的名稱(baseName = "SharedLogic")匯出,並使用一般的 import 陳述式匯入:import SharedLogic。
為 SQLDelight 新增動態連結旗標
預設情況下,IntelliJ IDEA 產生的專案已設定為靜態連結 iOS 框架。
若要在 iOS 上使用原生 SQLDelight 驅動程式,請新增動態連結器旗標,讓 Xcode 工具集能夠找到系統提供的 SQLite 二進位檔:
在 IntelliJ IDEA 中,選取 File | Open Project in Xcode 選項以在 Xcode 中開啟專案。
在 Xcode 中,點擊專案名稱以開啟其設定。
切換至 Build Settings 標籤頁,切換到 All 清單,並搜尋 Other Linker Flags 欄位。
展開該欄位,按下 Debug 欄位旁的加號,並將
-lsqlite3字串貼入 Any Architecture | Any SDK 中。對 Other Linker Flags | Release 欄位重複此程序。

返回 IntelliJ IDEA。
準備用於 iOS 相依注入的 Koin 類別
若要在 Swift 程式碼中使用 Koin 類別與函式,請建立一個特殊的 KoinComponent 類別並宣告適用於 iOS 的 Koin 模組。
在
sharedLogic/src/iosMain/kotlin/com/jetbrains/spacetutorial目錄中建立KoinHelper.kt檔案。新增
KoinHelper類別,它將透過延遲 Koin 注入封裝SpaceSDK類別:kotlinpackage com.jetbrains.spacetutorial import org.koin.core.component.KoinComponent import com.jetbrains.spacetutorial.entity.RocketLaunch import org.koin.core.component.inject class KoinHelper : KoinComponent { private val sdk: SpaceSDK by inject<SpaceSDK>() suspend fun getLaunches(forceReload: Boolean): List<RocketLaunch> { return sdk.getLaunches(forceReload = forceReload) } }在
KoinHelper類別下方新增initKoin()函式,你將在 Swift 中使用它來初始化並啟動 iOS Koin 模組:kotlinimport com.jetbrains.spacetutorial.cache.IOSDatabaseDriverFactory import com.jetbrains.spacetutorial.network.SpaceApi import org.koin.core.context.startKoin import org.koin.dsl.module fun initKoin() { startKoin { modules(module { single<SpaceApi> { SpaceApi() } single<SpaceSDK> { SpaceSDK( databaseDriverFactory = IOSDatabaseDriverFactory(), api = get() ) } }) } }
現在,你可以在 iOS 應用程式中啟動 Koin 模組,將原生資料庫驅動程式與通用 SpaceSDK 類別結合使用。
實作 UI
首先,你將建立一個 RocketLaunchRow SwiftUI 檢視以顯示清單中的項目。它將以 HStack 和 VStack 檢視為基礎。RocketLaunchRow 結構上會有擴充功能,包含用於顯示資料的實用幫助程式。
在 IntelliJ IDEA 中,確認你位於 Project 檢視。
在
iosApp/iosApp資料夾中(位於ContentView.swift旁邊)建立新的 Swift 檔案,並將其命名為RocketLaunchRow。使用以下程式碼更新
RocketLaunchRow.swift檔案:Swiftimport SwiftUI import SharedLogic struct RocketLaunchRow: View { var rocketLaunch: RocketLaunch var body: some View { HStack() { VStack(alignment: .leading, spacing: 10.0) { Text("\(rocketLaunch.missionName)") .font(.system(size: 18)) .bold() .fixedSize(horizontal: false, vertical: true) Text(launchText).foregroundColor(launchColor) Text("Launch year: \(String(rocketLaunch.launchYear))") Text("\(rocketLaunch.status.description_)") } Spacer() } } } extension RocketLaunchRow { private var launchText: String { let isSuccess = rocketLaunch.status.id == 3 return isSuccess ? "Successful" : "Unsuccessful" } private var launchColor: Color { let isSuccess = rocketLaunch.status.id == 3 return isSuccess ? Color.green : Color.red } }發射清單將顯示在
ContentView檢視中,該檢視已包含在專案中。在
ContentView.swift檔案中,為ContentView類別新增一個擴充,其中包含用於準備和管理資料的ViewModel類別:Swiftextension ContentView { enum LoadableLaunches { case loading case result([RocketLaunch]) case error(String) } @MainActor class ViewModel: ObservableObject { @Published var launches = LoadableLaunches.loading } }ViewModel(
ContentView.ViewModel)透過 Combine 架構與檢視(ContentView)連線:ContentView.ViewModel類別宣告為ObservableObject。@Published屬性用於launches屬性,因此每當此屬性變更時,ViewModel 都會發出信號。
移除
ContentView_Previews結構:你不需要實作與你的 ViewModel 相容的預覽。更新
ContentView類別的主體以顯示發射清單並新增重新載入功能。- 這是 UI 基礎工作:你將在本教學的下一階段實作
loadLaunches函式。 viewModel屬性使用@ObservedObject屬性標記,以訂閱 ViewModel。
swiftstruct ContentView: View { @ObservedObject private(set) var viewModel: ViewModel var body: some View { NavigationView { listView() .navigationBarTitle("Space Launches") .navigationBarItems(trailing: Button("Reload") { self.viewModel.loadLaunches(forceReload: true) }) } } private func listView() -> AnyView { switch viewModel.launches { case .loading: return AnyView(Text("Loading...").multilineTextAlignment(.center)) case .result(let launches): return AnyView(List(launches) { launch in RocketLaunchRow(rocketLaunch: launch) }) case .error(let description): return AnyView(Text(description).multilineTextAlignment(.center)) } } }- 這是 UI 基礎工作:你將在本教學的下一階段實作
RocketLaunch類別用作初始化List檢視的參數,因此它需要符合Identifiable協定。 該類別已有名為id的屬性,因此你只需在ContentView.swift底部新增一個擴充:Swiftextension RocketLaunch: Identifiable { }
載入資料
若要在 ViewModel 中擷取關於火箭發射的資料,你將需要 Multiplatform 程式庫中的 KoinHelper 類別執行個體。 它將允許你使用正確的資料庫驅動程式呼叫 SDK 函式。
在
ContentView.swift檔案中,擴充ViewModel類別以包含KoinHelper物件與loadLaunches函式:Swiftextension ContentView { // ... class ViewModel: ObservableObject { // ... let helper: KoinHelper = KoinHelper() init() { self.loadLaunches(forceReload: false) } func loadLaunches(forceReload: Bool) { // TODO: retrieve data } } }在
loadLaunches()函式中呼叫KoinHelper.getLaunches()函式 (它會將呼叫代理至SpaceSDK類別), 並將結果儲存於launches屬性中:Swiftfunc loadLaunches(forceReload: Bool) { Task { do { self.launches = .loading let launches = try await helper.getLaunches(forceReload: forceReload) self.launches = .result(launches) } catch { self.launches = .error(error.localizedDescription) } } }當你將 Kotlin 模組編譯為 Apple 框架時,可以使用 Swift 的
async/await機制來呼叫掛起函式。由於
getLaunches函式在 Kotlin 中標記了@Throws(Exception::class)註解,因此任何作為Exception類別或其子類別執行個體的例外都將作為NSError傳遞至 Swift。 因此,所有此類例外都可以被loadLaunches()函式擷取。前往應用程式的入口點
iOSApp.swift檔案,並初始化 Koin 模組、檢視以及 ViewModel:Swiftimport SwiftUI import SharedLogic @main struct iOSApp: App { init() { KoinHelperKt.doInitKoin() } var body: some Scene { WindowGroup { ContentView(viewModel: .init()) } } }在 IntelliJ IDEA 中,切換至 iosApp 配置,選擇一個模擬器,然後執行它以檢視結果:

你可以在 final 分支上找到專案的最終版本。
下一步?
本教學介紹了一些潛在耗費資源的操作,例如剖析 JSON 以及在主執行緒中向資料庫發出請求。若要了解如何編寫並行程式碼並最佳化你的應用程式,請參閱協同程式指南。
你也可以查看這些額外的學習資源:
