Skip to content

Navigation 3 ​

本页展示了如何在 Koin 模块中声明 Navigation 3 条目并将其传递给 NavDisplay。每个功能模块贡献其各自的屏幕,而应用程序通过一个条目提供程序收集所有屏幕。本文假定你已了解 Navigation 3 的基础知识(返回栈、NavDisplay、NavEntry)以及 Compose 中的 ViewModel。

本页上的所有 API 均标记为 @KoinExperimentalAPI。

配置 ​

kotlin
// shared/build.gradle.kts,或在 Android 上的 app/build.gradle.kts
plugins {
    kotlin("plugin.serialization")
}

commonMain.dependencies {
    implementation("io.insert-koin:koin-compose-navigation3:$koin_version")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:$serialization_version")
}

koin-compose-navigation3 支持 Android、iOS、JVM 桌面端、JS 和 Wasm。

声明条目 ​

路由是带有 @Serializable 注解的类:

kotlin
@Serializable data object HomeRoute
@Serializable data class DetailRoute(val itemId: String)

在模块中为每个路由声明一个 navigation<T> { }。该 lambda 表达式是一个接收路由的 Composable:

kotlin
import org.koin.dsl.navigation3.navigation

val homeModule = module {
    viewModel<HomeViewModel>()

    navigation<HomeRoute> {
        HomeScreen(viewModel = koinViewModel())
    }
}

val detailModule = module {
    viewModel<DetailViewModel>()

    navigation<DetailRoute> { route ->
        DetailScreen(viewModel = koinViewModel { parametersOf(route.itemId) })
    }
}

每个 navigation<T> 均作为由路由类型限定的定义进行存储。该 lambda 表达式以 Koin 的 Scope 作为接收者运行,因此你可以在其中调用 get<T>() 以及诸如 koinViewModel() 等 Composable 函数。

构建条目提供程序 ​

koinEntryProvider() 将当前作用域的每个 navigation<T> 条目收集到一个供 NavDisplay 使用的提供程序中:

kotlin
import org.koin.compose.navigation3.koinEntryProvider

@Composable
fun App() {
    val backStack = remember { mutableStateListOf<Any>(HomeRoute) }

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        entryProvider = koinEntryProvider()
    )
}

koinEntryProvider<T>() 接收返回栈的路由类型:搭配 rememberNavBackStack() 使用时的 NavKey,或者在 NavDisplay 指定了类型时你自己的路由类型(指定类型的 SceneStrategy,例如 rememberSupportingPaneSceneStrategy<Route>(),会使其成为 NavDisplay<Route>)。如果保留为 Any,构建将会失败并提示:Argument type mismatch: actual type is 'Function1<Any, NavEntry<Any>>', but 'Function1<Route, NavEntry<Route>>' was expected.。

在 Android Activity 中 ​

在 Android 上,ComponentCallbacks 上的两个扩展函数可以从 Activity 或 Fragment 作用域构建提供程序:

函数行为
entryProvider<T>()延迟委托:val provider by entryProvider<Any>()
getEntryProvider<T>()立即构建提供程序

它们从组件的 Koin 作用域进行解析:如果组件实现了 AndroidScopeComponent,则为 Activity 作用域,否则为根作用域。

作用域内的条目 ​

当屏幕需要与特定作用域同生命周期的对象时,请在作用域内部声明条目。使用 activityRetainedScope,它们可以在配置更改(configuration changes)后继续存留:

kotlin
class Navigator(start: Any) {
    val backStack = mutableStateListOf(start)
    fun goTo(route: Any) { backStack.add(route) }
    fun goBack() { backStack.removeLastOrNull() }
}

val appModule = module {
    activityRetainedScope {
        scoped { Navigator(start = ConversationList) }

        navigation<ConversationList> {
            val navigator = get<Navigator>()
            ConversationListScreen(onClick = { navigator.goTo(ConversationDetail(it)) })
        }

        navigation<ConversationDetail> { route ->
            ConversationDetailScreen(conversationId = route.id)
        }
    }
}

class MainActivity : ComponentActivity(), AndroidScopeComponent {
    override val scope: Scope by activityRetainedScope()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            val navigator: Navigator = get()
            NavDisplay(
                backStack = navigator.backStack,
                onBack = { navigator.goBack() },
                entryProvider = getEntryProvider()
            )
        }
    }
}

getEntryProvider() 从 Activity 作用域中读取条目。在某个作用域内声明的条目仅对该作用域可见。关于 activityRetainedScope 的说明,请参阅 Android 作用域。

条目的 ViewModel ​

若要将 ViewModel 的作用域限定为其对应的条目,请向 NavDisplay 添加 ViewModel store 装饰器。如果不添加,koinViewModel() 将使用 Activity 的 store,同一路由的每个条目都会共享同一个实例:

kotlin
NavDisplay(
    backStack = backStack,
    onBack = { backStack.removeLastOrNull() },
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        rememberViewModelStoreNavEntryDecorator()
    ),
    entryProvider = koinEntryProvider()
)

将路由或其字段作为形参传递:

kotlin
class DetailViewModel(
    @InjectedParam val route: DetailRoute,
    private val repository: ItemRepository
) : ViewModel()

val detailModule = module {
    viewModel<DetailViewModel>()

    navigation<DetailRoute> { route ->
        DetailScreen(viewModel = koinViewModel { parametersOf(route) })
    }
}
kotlin
@KoinViewModel
class DetailViewModel(
    @InjectedParam val route: DetailRoute,
    private val repository: ItemRepository
) : ViewModel()

// navigation<T> 条目在 DSL 模块中声明
val detailModule = module {
    navigation<DetailRoute> { route ->
        DetailScreen(viewModel = koinViewModel { parametersOf(route) })
    }
}
kotlin
class DetailViewModel(
    val route: DetailRoute,
    private val repository: ItemRepository
) : ViewModel()

val detailModule = module {
    viewModelOf(::DetailViewModel) // route 来自 parametersOf(route)

    navigation<DetailRoute> { route ->
        DetailScreen(viewModel = koinViewModel { parametersOf(route) })
    }
}

条目元数据 ​

navigation<T> 接收一个传递给 NavEntry 的 metadata 映射。可将其用于针对每个条目的转场过渡,或诸如列表-详情等场景策略:

kotlin
val conversationModule = module {
    navigation<ConversationList>(metadata = ListDetailSceneStrategy.listPane()) {
        ConversationListScreen()
    }

    navigation<ConversationDetail>(metadata = ListDetailSceneStrategy.detailPane()) { route ->
        ConversationDetailScreen(route.id)
    }

    navigation<ModalRoute>(
        metadata = NavDisplay.transitionSpec {
            slideInVertically(initialOffsetY = { it }) togetherWith ExitTransition.KeepUntilTransitionsFinished
        }
    ) {
        ModalScreen()
    }
}

然后将场景策略传递给 NavDisplay(sceneStrategy = rememberListDetailSceneStrategy())。元数据的键来自 Navigation 3 和自适应布局库,而非来自 Koin。

从 Navigation 2 迁移 ​

Navigation 2搭配 Koin 的 Navigation 3
NavHost { composable(...) } 中的字符串或类型化路由@Serializable 路由类
NavHost 中的 composable<Route> { ... }Koin 模块中的 navigation<Route> { ... }
NavHost(navController, startDestination)NavDisplay(backStack, entryProvider = koinEntryProvider())
从 SavedStateHandle 读取实参传递给 lambda 表达式的路由对象

API 汇总 ​

API软件包用途
Module.navigation<T>(metadata) { }org.koin.dsl.navigation3在模块中声明条目
ScopeDSL.navigation<T>(metadata) { }org.koin.dsl.navigation3在作用域中声明条目
koinEntryProvider<T>(scope)org.koin.compose.navigation3来自当前 Compose 作用域的条目提供程序
entryProvider<T>(), getEntryProvider<T>()org.koin.androidx.compose.navigation3来自 Activity 或 Fragment 的条目提供程序 (Android)