Skip to content

DSL 参考 ​

本页以表格形式列出了所有 Koin DSL 关键字,附带需导入的软件包以及解释其用法的页面链接。其中涵盖了三种 DSL 形式:编译器插件 DSL(Compiler Plugin DSL)、构造函数 DSL(Constructor DSL,构造函数引用)和经典 DSL(Classic DSL,lambda)。关于注解,请参阅注解参考。

DSL 风格 ​

风格示例导入
编译器插件 DSLsingle<UserRepository>()org.koin.plugin.module.dsl.*
构造函数 DSLsingleOf(::UserRepository)org.koin.core.module.dsl.*
经典 DSLsingle { UserRepository(get()) }org.koin.dsl.*

编译器插件 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 体内部的操作。要选择适合的风格,请参阅选择您的风格。

应用程序 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、可变参数(vararg)或 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 工厂
workManagerFactory()koin-androidx-workmanagerWorkManager
slf4jLogger(level)koin-logger-slf4jKtor

模块 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>

定义 ​

每个关键字创建的内容在定义中有详细解释。

定义编译器插件 DSL构造函数 DSL经典 DSL
Singlesingle<T>()singleOf(::T)single { T(get()) }
Factoryfactory<T>()factoryOf(::T)factory { T(get()) }
Scoped(在作用域块中)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()) }

软件包:

关键字编译器插件 DSL构造函数 / 经典 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>()
    }
}

作用域 DSL ​

作用域块对生命周期与该作用域相同的定义进行分组。请参阅作用域。

函数软件包功能说明
scope<T> { }Module 成员由类型 T 标识的作用域,通常为作用域源的类型
scope(named("session")) { }Module 成员由限定符标识的作用域

在作用域块内部:

定义编译器插件 DSL构造函数 DSL经典 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>()
    }
}

作用域原型(Archetype) ​

原型是针对某种作用域源类型而非单个类的作用域块。该种类的每个源都会获得这些定义。

函数工件作用域归属参见
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 作用域