新增多平台程式庫的相依性
每個程式都需要一組程式庫才能成功運行。 Kotlin Multiplatform 專案可以相依於支援多個目標平台的跨平台程式庫、平台專用程式庫以及其他多平台專案。
如果你有開發 Android 應用程式的經驗,新增多平台相依性類似於在一般的 Android 專案中新增 Gradle 相依性。 主要差別在於你必須將相依性新增至特定的原始碼集,而不是整個模組。
本頁介紹了在多平台專案中管理相依性的整體方法。 有關某些平台的具體細節,請參閱新增 Android 相依性與新增 iOS 相依性。
相依性類型
在 Kotlin Multiplatform 專案中,你可以使用兩種類型的相依性:
多平台相依性(Multiplatform dependencies)。這些是支援多個目標且可用於共用原始碼集的多平台程式庫。
許多現代 Android 程式庫都已經支援多平台,例如 Koin、Coil 和 SQLDelight。
可以在 klibs.io 上尋找更多多平台程式庫,這是一個已發佈的 Kotlin Multiplatform 程式庫目錄。
原生相依性(Native dependencies)。這些是來自相應生態系統的平台專用程式庫。 在原生專案中,你通常透過平台專屬工具來管理這些程式庫,例如適用於 Android 的 Gradle 和適用於 iOS 的 Swift Package Manager。
當你處理多平台專案模組時,通常仍需要原生相依性來使用平台 API,例如安全儲存、系統呼叫等。 在建置指令碼中,你在原生原始碼集(例如
androidMain和iosMain)的配置中指定原生相依性。
對於這兩種類型的相依性,你都可以使用本機和外部儲存庫。
Gradle version catalogs
使用 Gradle 時,我們建議使用 version catalogs 來管理相依性。
透過 version catalogs,你可以在目錄中定義構件名稱和版本,然後在建置指令碼檔案中參照此定義。
例如,這是一個基本的目錄檔案:
# libs.versions.toml,預設的目錄檔案
[versions]
my-library = "1.0"
[libraries]
my-library = {module = "com.example:my-library", version.ref = "my-library"}這是使用該目錄新增相依性的範例:
// build.gradle.kts
dependencies {
// 'libs' 是目錄檔案名稱的第一部分
// 'my.library' 是沒有命名空間的構件名稱,
// 且以點號代替連字號
implementation(libs.my.library)
}對核心 Kotlin 程式庫的相依性
標準程式庫
Kotlin Multiplatform 專案中的每個原始碼集都會自動相依於 Kotlin 標準程式庫 (kotlin-stdlib)。 標準程式庫的版本與所套用的 Kotlin Multiplatform Gradle 外掛程式版本相同。
對於平台專用原始碼集,Gradle 會自動使用該程式庫對應的平台專用變體,而其餘原始碼集則新增共用標準程式庫。 對於 JVM 目標,Kotlin Gradle 外掛程式會根據 Gradle 建置指令碼中的 compilerOptions.jvmTarget 編譯器選項選取適當的 JVM 標準程式庫。
了解如何變更預設的 kotlin-stdlib 相依性解析。
測試程式庫
對於多平台測試,可以使用 kotlin.test API。 由於它是一個多平台程式庫,你只需為 commonTest 原始碼集指定單一相依性,即可將測試相依性新增至所有原始碼集:
kotlin {
//...
sourceSets {
// 讓 kotlin.test 類別在所有測試原始碼集中可用
commonTest.dependencies {
implementation(kotlin("test"))
}
}
}kotlin {
//...
sourceSets {
// 讓 kotlin.test 類別在所有測試原始碼集中可用
commonTest {
dependencies {
implementation kotlin("test")
}
}
}
}kotlinx 程式庫
kotlinx 程式庫是由 JetBrains 的 Kotlin 核心團隊維護的多平台程式庫(主要範例包括 kotlinx.serialization 和 kotlinx.coroutines)。
與任何其他多平台程式庫一樣,若要新增相依性,只需在對應的原始碼集中參照程式庫構件即可。
kotlinx 程式庫有時需要更複雜的設定,例如針對 Web 目標。 請參閱該程式庫的文件以獲取完整指引。
對 Kotlin Multiplatform 程式庫的相依性
你可以新增對採用 Kotlin Multiplatform 的程式庫的相依性,例如 SQLDelight。 這些程式庫的作者通常會提供將其相依性新增至專案的指南。
在 klibs.io 上尋找 Kotlin Multiplatform 程式庫
Gradle version catalog 範例
使用 Gradle 時,建議使用 version catalogs。 以下是定義了下述範例中所使用之所有程式庫的 version catalog:
[versions]
ktor = "3.5.2"
kotlinx-coroutines = "1.11.0"
sqlDelight = "2.3.2"
[libraries]
ktor-clientCore = { module = "io.ktor:ktor-client-core", version.ref = "3.5.2" }
kotlinx-coroutinesCore = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "1.11.0" }
sqldelight-nativeDriver = { module = "com.squareup.sqldelight:native-driver", version.ref = "2.3.2" }所有原始碼集共用的程式庫
如果你希望從所有原始碼集存取該程式庫,或使用它來編寫共用程式碼,請僅將其新增至共用原始碼集。 Kotlin Multiplatform Gradle 外掛程式會自動為其他已宣告的原始碼集解析對應的平台專用構件。
共用原始碼集不能相依於平台專用構件:共用程式碼需要針對每個已宣告的目標進行編譯。
kotlin {
//...
sourceSets {
commonMain.dependencies {
implementation(libs.ktor.clientCore)
}
androidMain.dependencies {
// 對 ktor-client 平台專屬部分的相依性會在建置時進行解析
}
}
}kotlin {
//...
sourceSets {
commonMain {
dependencies {
implementation(libs.ktor.clientCore)
}
}
androidMain {
dependencies {
// 對 ktor-client 平台專屬部分的相依性會在建置時進行解析
}
}
}
}你也可以在頂層的 dependencies {} 區塊中設定共用程式庫。 請參閱在頂層設定相依性。
在特定原始碼集中使用的程式庫
如果你只想在特定原始碼集中使用某個多平台程式庫,可以只將其新增至這些原始碼集中。 這樣該程式庫的宣告就只會在這些原始碼集中可用。
在這種情況下,請使用共用程式庫名稱,而不是平台專用名稱:Kotlin Multiplatform Gradle 外掛程式會自動解析此類參照。 確切的名稱通常會在該程式庫的文件中說明。
以下範例針對平台專屬的 SQLDelight 使用 native-driver 而非 native-driver-iosx64:
kotlin {
//...
sourceSets {
commonMain.dependencies {
// kotlinx.coroutines 在所有原始碼集中可用
implementation(libs.kotlinx.coroutinesCore)
}
androidMain.dependencies {
// 放置 Android 專用相依性的位置
}
iosMain.dependencies {
// SQLDelight 在 iOS 原始碼集中可用,
// 但在 Android 或共用原始碼集中不可用
implementation(libs.sqldelight.nativeDriver)
}
}
}kotlin {
//...
sourceSets {
commonMain {
dependencies {
// kotlinx.coroutines 在所有原始碼集中可用
implementation(libs.kotlinx.coroutinesCore)
}
}
androidMain {
dependencies {
// 放置 Android 專用相依性的位置
}
}
iosMain {
dependencies {
// SQLDelight 在 iOS 原始碼集中可用,
// 但在 Android 或共用原始碼集中不可用
implementation(sqldelight.nativeDriver)
}
}
}
}對另一個多平台專案的相依性
一個多平台專案可以相依於另一個多平台專案。 若要進行此設定,請將 Gradle 專案相依性新增至需要它的原始碼集。 如果你想在所有原始碼集中使用專案相依性,請將其新增至共用原始碼集。 在這種情況下,編譯器會自動為其他原始碼集提供該專案的平台專用構件。
kotlin {
//...
sourceSets {
commonMain.dependencies {
implementation(project(":some-other-multiplatform-module"))
}
androidMain.dependencies {
// :some-other-multiplatform-module 的平台專用宣告
// 將會自動解析
}
}
}kotlin {
//...
sourceSets {
commonMain {
dependencies {
implementation project(':some-other-multiplatform-module')
}
}
androidMain {
dependencies {
// :some-other-multiplatform-module 的平台專用宣告
// 將會自動解析
}
}
}
}後續步驟
查看有關在多平台專案中新增相依性的其他資源,進一步了解:
取得協助
- Kotlin Slack。取得邀請並加入 #multiplatform 頻道。
- Kotlin 問題追蹤器。回報新問題。
