Kotlin Multiplatform 設定
本頁面介紹如何在 Kotlin Multiplatform (KMP) 專案中設定 Koin:Gradle 相依性、Koin 程式碼放置位置、一個啟動 Koin 的共享函式,以及各平台如何呼叫它。本文假設你已了解模組與啟動 Koin。有關如何為各平台提供專屬實作的內容,請參閱 KMP 共享模式。
支援的目標
koin-core 與編譯器外掛程式支援每一個 Kotlin 目標:
| 目標 | 支援 |
|---|---|
| Android | 是 |
iOS (iosArm64, iosX64, iosSimulatorArm64) | 是 |
| JVM(桌面、伺服器) | 是 |
JS 與 Wasm (js, wasmJs) | 是 |
| macOS、Linux、Windows (Kotlin/Native) | 是 |
Compose 構件遵循 Compose Multiplatform 的目標。請參閱 Gradle 設定中的構件表格。
相依性
將 Koin 編譯器外掛程式套用至 shared 模組,並將 Koin 新增至原始碼集:
// shared/build.gradle.kts
plugins {
kotlin("multiplatform")
alias(libs.plugins.koin.compiler)
}
kotlin {
androidTarget()
iosArm64()
iosSimulatorArm64()
jvm()
sourceSets {
commonMain.dependencies {
implementation(project.dependencies.platform(libs.koin.bom))
implementation(libs.koin.core)
implementation(libs.koin.annotations) // 僅搭配註解使用
// Compose Multiplatform
implementation(libs.koin.compose)
implementation(libs.koin.compose.viewmodel)
}
androidMain.dependencies {
implementation(libs.koin.android)
}
commonTest.dependencies {
implementation(libs.koin.test)
}
}
}編譯器外掛程式只需一次宣告即可在每個目標上執行。與 Koin Annotations 1.x 的 KSP 設定不同,此處不需要個別目標的配置(請參閱從 KSP 遷移)。
專案結構
shared/
└── src/
├── commonMain/kotlin/di/
│ ├── Koin.kt // 模組與 initKoin()
│ └── PlatformModule.kt // expect 宣告
├── androidMain/kotlin/di/
│ └── PlatformModule.android.kt
└── iosMain/kotlin/di/
└── PlatformModule.ios.kt
androidApp/ // Application 類別呼叫 initKoin()
iosApp/ // Swift App 呼叫 initKoin()共享定義位於 commonMain。各平台的原始碼集僅包含不同平台之間有差異的內容。
共享啟動函式
在 commonMain 中撰寫一個啟動 Koin 的函式。各平台呼叫該函式,並可透過 config 參數新增各自的配置:
// commonMain/kotlin/di/Koin.kt
import org.koin.core.context.startKoin
import org.koin.dsl.KoinAppDeclaration
import org.koin.dsl.includes
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*
val dataModule = module {
single<UserRepository>()
viewModel<UserViewModel>()
}
val appModule = module {
includes(dataModule, platformModule())
}
fun initKoin(config: KoinAppDeclaration? = null) {
startKoin {
includes(config)
modules(appModule)
}
}// commonMain/kotlin/di/Koin.kt
import org.koin.core.annotation.*
import org.koin.dsl.KoinAppDeclaration
import org.koin.dsl.includes
import org.koin.plugin.module.dsl.startKoin
@Module(includes = [PlatformModule::class])
@ComponentScan("com.example.app")
@Configuration
class AppModule
@KoinApplication
object KoinApp
fun initKoin(config: KoinAppDeclaration? = null) {
startKoin<KoinApp> {
includes(config)
}
}@Configuration 模組會在建置期由 @KoinApplication 尋找。PlatformModule 是一個 expect 模組類別,請參閱 KMP 共享模式。
// commonMain/kotlin/di/Koin.kt
import org.koin.core.context.startKoin
import org.koin.core.module.dsl.*
import org.koin.dsl.KoinAppDeclaration
import org.koin.dsl.includes
import org.koin.dsl.module
val dataModule = module {
singleOf(::UserRepository)
viewModelOf(::UserViewModel)
}
val appModule = module {
includes(dataModule, platformModule())
}
fun initKoin(config: KoinAppDeclaration? = null) {
startKoin {
includes(config)
modules(appModule)
}
}includes(config) 會將平台配置(Android context、記錄器、額外模組)套用至同一個 Koin 啟動流程。platformModule() 是一個 expect 函式,請參閱 KMP 共享模式。
平台入口點
Android
從你的 Application 類別呼叫 initKoin 並傳入 Android context:
// androidApp
class MainApplication : Application() {
override fun onCreate() {
super.onCreate()
initKoin {
androidContext(this@MainApplication)
androidLogger()
}
}
}接著,Android 定義便可將 Context 作為建構函式參數使用。請參閱 Android 啟動。
iOS
在 iosMain 中新增一個無參數的函式,並從 Swift 的 App 初始設定式中呼叫它:
// iosMain/kotlin/di/KoinIos.kt
fun initKoinIos() = initKoin()// iosApp/iOSApp.swift
import Shared
@main
struct iOSApp: App {
init() {
KoinIosKt.doInitKoinIos()
}
var body: some Scene {
WindowGroup { ContentView() }
}
}Kotlin/Native 命名規則解釋了 Swift 的呼叫方式。KoinIos.kt 的頂層函式會匯出至名為 KoinIosKt 的類別中。名稱以 init 開頭的函式會獲得 do 前綴,因此 initKoinIos 會變成 doInitKoinIos。這個輔助函式避免了從 Swift 傳遞 Kotlin Lambda(config)。
在 Swift 程式碼中呼叫 Koin 的相關內容,請參閱 KMP 平台整合。
JVM 桌面
// jvmMain
fun main() = application {
initKoin {
printLogger()
}
Window(onCloseRequest = ::exitApplication) {
App()
}
}Web
// jsMain or wasmJsMain
fun main() {
initKoin()
// 啟動你的 UI
}Compose Multiplatform
使用 Compose Multiplatform 時,你可以透過 KoinApplication 直接從根 Composable 啟動 Koin,而無需在各平台上呼叫 initKoin。在 Android 上,它會自動為你設定 Android context:
// commonMain
@Composable
fun App() {
KoinApplication(configuration = koinConfiguration { modules(appModule) }) {
MainScreen()
}
}// commonMain
@Composable
fun App() {
KoinApplication(configuration = koinConfiguration<KoinApp>()) {
MainScreen()
}
}koinConfiguration<T>() 來自於 org.koin.plugin.module.dsl。
// commonMain
@Composable
fun App() {
KoinApplication(configuration = koinConfiguration { modules(appModule) }) {
MainScreen()
}
}如果 Compose 之外的程式碼在第一個畫面顯示前就需要使用 Koin(背景服務、Swift 程式碼),請保留 initKoin。這兩種選項的比較請參閱 Koin for Compose。
相關內容
- KMP 共享模式:平台模組與
expect/actual定義。 - KMP 平台整合:共享程式碼中的 Android context、Swift 互通性、桌面與 Web。
- Koin for Compose:
KoinApplication與koinInject()。 - ViewModel:由 Android 與 Compose Multiplatform 共享的 ViewModel。
- Gradle 設定:BOM、版本目錄(version catalog)與構件清單。
