ViewModel
本页面介绍了如何在支持 AndroidX ViewModel 的各个平台(Android、iOS、桌面端、Web)上的 Koin 模块中声明 ViewModel。本文假设你已了解定义。要获取 ViewModel,请参阅具体平台页面:在 Activity 或 Fragment 中使用 by viewModel() 请参阅 Android ViewModel;使用 koinViewModel() 请参阅 Compose 中的 ViewModel。
依赖项
声明 DSL 位于 koin-core-viewmodel 中,这是一个多平台构件:
// build.gradle.kts, commonMain
implementation("io.insert-koin:koin-core-viewmodel")注入 API 随平台构件提供:io.insert-koin:koin-android(其中包含 koin-core-viewmodel)和 io.insert-koin:koin-compose-viewmodel。版本由 BOM 统一管理:参见 Gradle 设置。
声明 ViewModel
import org.koin.dsl.module
import org.koin.plugin.module.dsl.viewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()
val appModule = module {
viewModel<UserViewModel>()
}import org.koin.core.annotation.KoinViewModel
@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()使用编译器插件时,@KoinViewModel 位于 org.koin.core.annotation 中,并可在公共代码中生效。KSP 处理器则使用 org.koin.android.annotation.KoinViewModel。
import org.koin.dsl.module
import org.koin.core.module.dsl.viewModelOf
import org.koin.core.module.dsl.viewModel
val appModule = module {
viewModelOf(::UserViewModel)
// 或者显式编写构造函数调用
viewModel { UserViewModel(get()) }
}viewModel 定义类似于 factory,在每次请求时都会创建一个新实例。平台层的 ViewModelStore(Activity、Fragment、导航条目)会保留该实例,因此在 Android 上的配置发生变更时,相同的所有者会取回相同的 ViewModel。请勿将 ViewModel 声明为 single:否则它将被所有屏幕共享且永远不会被清除。
传递参数
ViewModel 通常需要仅在运行时才知道的值(例如条目 ID)。将构造函数形参标记为注入参数:
class DetailViewModel(
@InjectedParam val itemId: String,
private val repository: DetailRepository,
) : ViewModel()
val appModule = module {
viewModel<DetailViewModel>()
}@KoinViewModel
class DetailViewModel(
@InjectedParam val itemId: String,
private val repository: DetailRepository,
) : ViewModel()val appModule = module {
viewModel { params ->
DetailViewModel(itemId = params.get(), repository = get())
}
}viewModelOf(::DetailViewModel) 同样适用:它会根据调用方传入的值,按类型读取形参。
无论采用何种声明风格,调用方均通过 parametersOf 传递该值:
// Android
val viewModel: DetailViewModel by viewModel { parametersOf("item_123") }
// Compose
val viewModel = koinViewModel<DetailViewModel> { parametersOf("item_123") }形参只会在创建 ViewModel 时读取一次。如果同一个所有者使用另一个值再次发起请求,获取到的仍是现有实例。关于形参的更多信息,请参阅注入参数。
SavedStateHandle
在构造函数中添加 SavedStateHandle 形参。Koin 会直接从 ViewModel 的 CreationExtras 中创建它,无需额外声明:
class ProfileViewModel(
private val handle: SavedStateHandle,
private val repository: UserRepository,
) : ViewModel() {
val userId: String? = handle["userId"]
}
val appModule = module {
viewModel<ProfileViewModel>()
}@KoinViewModel
class ProfileViewModel(
private val handle: SavedStateHandle,
private val repository: UserRepository,
) : ViewModel() {
val userId: String? = handle["userId"]
}val appModule = module {
viewModelOf(::ProfileViewModel)
// 或者:由 get() 解析 SavedStateHandle
viewModel { ProfileViewModel(get(), get()) }
}在 Android 上,导航实参和 Activity extras 都保存在 SavedStateHandle 中。请仅在构造函数中注入它。如果 ViewModel 的所有者没有 SavedStateRegistryOwner,Koin 将抛出错误:"Koin could not create a SavedStateHandle: the ViewModel's CreationExtras has no SavedStateRegistryOwner."。
ViewModel 作用域
ViewModel 可以拥有一个作用域:依赖项随它一同创建,并在其被清除时一同释放。使用 viewModelScope 原型声明它们:
val appModule = module {
viewModelScope {
scoped<UserCache>()
viewModel<UserViewModel>()
}
}@ViewModelScope
class UserCache
@KoinViewModel
@ViewModelScope
class UserViewModel(private val cache: UserCache) : ViewModel()val appModule = module {
viewModelScope {
scopedOf(::UserCache)
viewModelOf(::UserViewModel)
}
}在启动时需启用该选项,否则 ViewModel 将无法获得作用域:
startKoin {
options(viewModelScopeFactory())
modules(appModule)
}viewModelScope 和 viewModelScopeFactory() 需要显式选择加入(Opt-in)@KoinViewModelScopeApi 与 @KoinExperimentalAPI。在构造函数中接收作用域依赖项的 ViewModel 必须在 viewModelScope { } 内声明。每个 ViewModel 实例都会获得专属的 UserCache,并在 ViewModel 被清除时关闭。
限制
- 每个所有者仅限一个实例:一旦该所有者的 ViewModel 实例已经存在,注入的参数将被忽略。若需要第二个实例,请使用不同的键或所有者。
- 不能使用
singleViewModel:单例 ViewModel 永远不会被清除,并且会导致其依赖项泄漏。 - 实验性 ViewModel 作用域:
viewModelScope被标记为实验性功能,未来可能会发生变更。
相关内容
- Android ViewModel:
by viewModel()、activityViewModel()、导航图 ViewModels。 - Compose 中的 ViewModel:
koinViewModel()和导航 ViewModels。 - 注入参数:
parametersOf与@InjectedParam。 - 作用域:作用域原型与作用域生命周期。
- 定义:其他定义类型。
