Skip to content

DSL 參考 ​

本頁以表格形式列出每個 Koin DSL 關鍵字,包含要匯入的套件以及說明該關鍵字之頁面的連結。內容涵蓋三種 DSL 形式:Compiler Plugin DSL、Constructor DSL(建構函式參照)以及 Classic DSL(Lambda)。關於註解,請參閱 註解參考。

DSL 風格 ​

風格範例匯入
Compiler Plugin DSLsingle<UserRepository>()org.koin.plugin.module.dsl.*
Constructor DSLsingleOf(::UserRepository)org.koin.core.module.dsl.*
Classic DSLsingle { UserRepository(get()) }org.koin.dsl.*

Compiler Plugin DSL 需要 Koin 編譯器外掛程式。該外掛程式會讀取建構函式、產生 get() 呼叫,並在建置期檢查相依關係圖。如果沒有該外掛程式,呼叫如 single<T>() 會在執行期擲出:Error while using 'single<T>()'. The Koin Compiler plugin is missing. Please fix your setup to use 'io.insert-koin.compiler.plugin' Koin Gradle Plugin.

當套用編譯器外掛程式時,建構函式參照形式(singleOf(::T))也會受到檢查。手寫的 Lambda 則不會:該外掛程式只追蹤它提供的型別,而非 Lambda 主體執行的內容。若要選擇適合的風格,請參閱 選擇你的風格。

Application DSL ​

用於建立並啟動 Koin 容器的函式。請參閱 啟動 Koin。

函式套件功能說明
startKoin { }org.koin.core.context建立 KoinApplication 並將其註冊至全域上下文。若已經啟動則擲出 KoinApplicationAlreadyStartedException
startKoin<T>()org.koin.plugin.module.dsl編譯器外掛程式:使用 @KoinApplication 類別 T 的模組啟動 Koin
koinApplication { }org.koin.dsl建立獨立的 KoinApplication,不註冊至全域。請參閱 上下文隔離
koinApplication<T>()org.koin.plugin.module.dsl編譯器外掛程式:包含 T 之模組的獨立應用程式
koinConfiguration { }org.koin.dsl宣告可重複使用的 KoinConfiguration 而不啟動 Koin
koinConfiguration<T>()org.koin.plugin.module.dsl編譯器外掛程式:包含 T 之模組的配置
stopKoin()org.koin.core.context關閉全域容器及其所有執行個體
loadKoinModules(module)org.koin.core.context將模組載入至已啟動的全域容器中
unloadKoinModules(module)org.koin.core.context卸載模組並捨棄其執行個體

startKoin { } 與 koinApplication { } 內部 ​

函式功能說明
modules(...)載入模組:單一 Module、可變參數或 List<Module>
modules(UserModule::class, ...)編譯器外掛程式:載入從 @Module 類別產生的模組
module<UserModule>()編譯器外掛程式:載入從單一 @Module 類別產生的模組
withConfiguration<T>()編譯器外掛程式:將 @KoinApplication 類別 T 的模組新增至現有應用程式
includes(configuration)套用一個或多個 KoinConfiguration 或 KoinAppDeclaration 區塊
printLogger(level)輸出記錄至標準輸出。預設層級為 Level.INFO
logger(logger)使用你自己的 Logger 實作。預設為 EmptyLogger(無輸出)
properties(map)從 Map<String, Any> 載入屬性
fileProperties(fileName)僅限 JVM。從檔案載入屬性,預設為 /koin.properties
environmentProperties()僅限 JVM。載入系統屬性與環境變數
allowOverride(Boolean)允許或禁止定義覆寫。預設為 true。請參閱 定義
createEagerInstances()建立 createdAtStart 定義。startKoin 與 koinApplication 已預先呼叫此函式
options(...)設定 Koin 選項,例如 viewModelScopeFactory()。請參閱 ViewModel
lazyModules(...)在背景載入延遲模組(koin-core-coroutines)。請參閱 延遲模組

modules(A::class)、module<T>() 與 withConfiguration<T>() 用於一般的 startKoin { } 或 koinApplication { } 中,而非 startKoin<T> { } 內部。

平台擴充功能為此區塊新增了更多函式:

函式構件參閱
androidContext(context), androidLogger(level), androidFileProperties()koin-androidAndroid 啟動
fragmentFactory()koin-androidFragment Factory
workManagerFactory()koin-androidx-workmanagerWorkManager
slf4jLogger(level)koin-logger-slf4jKtor

Module DSL ​

請參閱 模組 與 延遲模組。

函式套件功能說明
module { }org.koin.dsl宣告模組
module(createdAtStart = true) { }org.koin.dsl該模組中的每個 single 都會在啟動時建立
lazyModule { }org.koin.dsl宣告稍後在背景載入的模組(koin-core-coroutines)
includes(otherModule, ...)org.koin.dsl包含其他模組,以可變參數或 Collection<Module> 形式提供
moduleA + moduleBorg.koin.dsl建置 List<Module>

定義 ​

每個關鍵字所建立的內容已在 定義 中說明。

定義Compiler Plugin DSLConstructor DSLClassic DSL
Singlesingle<T>()singleOf(::T)single { T(get()) }
Factoryfactory<T>()factoryOf(::T)factory { T(get()) }
Scoped(在 scope 區塊中)scoped<T>()scopedOf(::T)scoped { T(get()) }
ViewModelviewModel<T>()viewModelOf(::T)viewModel { T(get()) }
Worker (Android)worker<T>()workerOf(::T)worker { T(get(), get()) }
Fragment (Android)不支援fragmentOf(::T)fragment { T(get()) }
函式或建構器single { create(::buildT) }singleOf(::buildT)single { buildT(get()) }

套件:

關鍵字Compiler Plugin DSLConstructor / Classic DSL
single, factory, scoped, createorg.koin.plugin.module.dslorg.koin.dsl (Lambda), org.koin.core.module.dsl (singleOf, factoryOf, scopedOf, new)
viewModel, viewModelOf(構件 koin-core-viewmodel)org.koin.plugin.module.dslorg.koin.core.module.dsl
worker, workerOf(構件 koin-androidx-workmanager)org.koin.plugin.module.dslorg.koin.androidx.workmanager.dsl
fragment, fragmentOf(構件 koin-android)org.koin.androidx.fragment.dsl

org.koin.androidx.viewmodel.dsl 與 org.koin.compose.viewmodel.dsl 中的 viewModel 和 viewModelOf 已棄用:請從 org.koin.core.module.dsl 匯入它們。

create(::buildT) 必須是其 Lambda 中的唯一指令。否則編譯器外掛程式會回報 create(::buildT) must be the only instruction in the lambda.。請參閱 定義。

Lambda 參數 ​

Lambda 定義具有以下簽章:

關鍵字參數
single(qualifier, createdAtStart) { }qualifier: Qualifier? = null, createdAtStart: Boolean = false
factory(qualifier) { }qualifier: Qualifier? = null
scoped(qualifier) { }qualifier: Qualifier? = null
viewModel(qualifier) { }qualifier: Qualifier? = null
worker(qualifier) { }qualifier: Qualifier = named<T>()

定義 Lambda 內部 ​

該 Lambda 以 Scope 為接收器並以 ParametersHolder 為引數(params)執行:

函式傳回值參閱
get<T>(), get<T>(qualifier)執行個體。若遺失則擲出 NoDefinitionFoundException注入
getOrNull<T>()執行個體或 null注入
inject<T>()Lazy<T>注入
getAll<T>()繫結至 T 的所有執行個體進階模式
getProperty(key), getProperty(key, default), getPropertyOrNull(key)Koin 屬性啟動 Koin
params.get<T>(), (id) -> ... 解構注入的參數注入參數
new(::T)新的 T,其每個建構函式參數皆由 get() 解析
create(::T)編譯器外掛程式:同上,並包含建置期檢查定義
getSource<T>()作用域來源物件作用域
androidContext(), androidApplication()Android Context 或 ApplicationAndroid 啟動

定義選項 ​

選項在定義之後套用,可透過中綴運算子或在 withOptions { } 區塊中使用。它們適用於每個定義關鍵字。

選項形式功能說明參閱
bindsingle<T>() bind I::class新增次要型別定義
bindssingle<T>() binds arrayOf(I::class, J::class)新增多個次要型別定義
onClosesingle<T>() onClose { it?.close() }執行個體釋放時的回呼定義
withOptions { }single<T>() withOptions { ... }開啟下方的選項區塊
.override()single<T> { ... }.override()當設定 allowOverride(false) 時,標記允許的覆寫定義

在 withOptions { } 中,或在 singleOf(::T) { }、factoryOf、scopedOf 及 viewModelOf 的尾隨區塊中:

選項功能說明
named("name")字串限定詞。請參閱 限定詞
named<Type>()型別限定詞
bind<I>()新增次要型別
binds(listOf(I::class, J::class))新增多個次要型別
createdAtStart()在 Koin 啟動時建立該 single
onClose { }釋放回呼
kotlin
val appModule = module {
    single<UserRepositoryImpl>() withOptions {
        named("local")
        bind<UserRepository>()
        createdAtStart()
    }

    // Constructor DSL
    singleOf(::UserRepositoryImpl) {
        named("local")
        bind<UserRepository>()
    }
}

Scope DSL ​

scope 區塊將生命週期與某個作用域相同的定義分組。請參閱 作用域。

函式套件功能說明
scope<T> { }Module 成員由型別 T 識別的作用域,通常為作用域來源的型別
scope(named("session")) { }Module 成員由限定詞識別的作用域

在 scope 區塊內部:

定義Compiler Plugin DSLConstructor DSLClassic DSL
Scopedscoped<T>()scopedOf(::T)scoped { T(get()) }
Factoryfactory<T>()factoryOf(::T)factory { T(get()) }
ViewModelviewModel<T>()viewModelOf(::T)viewModel { T(get()) }
Worker (Android)worker<T>()workerOf(::T)worker { T(get(), get()) }
kotlin
val sessionModule = module {
    scope<UserSession> {
        scoped<SessionCache>()
        factory<SessionPresenter>()
    }
}

Scope 原型 ​

原型是針對某種類型的作用域來源(而非單一類別)所設定的 scope 區塊。該類型的每個來源都會取得這些定義。

函式構件作用域對象參閱
viewModelScope { }koin-core-viewmodel每個 ViewModelViewModel
activityScope { }koin-android每個 ActivityAndroid 作用域
activityRetainedScope { }koin-android每個 Activity,在配置變更時予以保留Android 作用域
fragmentScope { }koin-android每個 FragmentAndroid 作用域
navigationScope { }koin-compose-viewmodel-navigation每個導覽目的地(NavBackStackEntry)Compose 作用域
requestScope { }koin-ktor每個 Ktor 呼叫Ktor 作用域