Navigation 3
このページでは、Koinモジュール内でNavigation 3のエントリを宣言し、それらをNavDisplayに渡す方法を説明します。各機能モジュールがそれぞれの画面を提供し、アプリはそれらすべてを単一のエントリプロバイダーで収集します。なお、Navigation 3の基本(バックスタック、NavDisplay、NavEntry)およびComposeにおけるViewModelについて理解していることを前提としています。
このページのすべてのAPIには@KoinExperimentalAPIのマークが付けられています。
セットアップ
// 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なクラスです。
@Serializable data object HomeRoute
@Serializable data class DetailRoute(val itemId: String)モジュール内でルートごとに1つのnavigation<T> { }を宣言します。ラムダはルートを受け取るComposableです。
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>はルート型によって修飾された定義として保存されます。ラムダはKoinのScopeをレシーバーとして実行されるため、その中でget<T>()を呼び出したり、koinViewModel()などのComposable関数を呼び出したりできます。
エントリプロバイダーの構築
koinEntryProvider()は、現在のスコープのすべてのnavigation<T>エントリを収集し、NavDisplay用の1つのプロバイダーにまとめます。
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が型指定されている場合は独自のルート型になります(rememberSupportingPaneSceneStrategy<Route>()のような型指定されたSceneStrategyを使用すると、NavDisplay<Route>になります)。Anyのままにすると、ビルドはArgument type mismatch: actual type is 'Function1<Any, NavEntry<Any>>', but 'Function1<Route, NavEntry<Route>>' was expected.というエラーで失敗します。
Android Activityからの利用
Androidでは、ComponentCallbacksの2つの拡張関数によって、ActivityまたはFragmentのスコープからプロバイダーを構築できます。
| 関数 | 動作 |
|---|---|
entryProvider<T>() | 遅延デリゲート: val provider by entryProvider<Any>() |
getEntryProvider<T>() | プロバイダーを即座に構築 |
これらはコンポーネントのKoinスコープから解決されます。AndroidScopeComponentを実装している場合はActivityスコープから、そうでない場合はルートスコープから解決されます。
スコープ内のエントリ
画面がそのスコープとともに生存するオブジェクトを必要とする場合は、スコープ内でエントリを宣言します。activityRetainedScopeを使用すると、これらは構成変更(Configuration change)をまたいで維持されます。
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 Scopesを参照してください。
エントリ用のViewModel
ViewModelのスコープをそのエントリに限定するには、NavDisplayにViewModel storeデコレーターを追加します。これがない場合、koinViewModel()はActivityのストアを使用するため、同じルートのすべてのエントリで1つのインスタンスが共有されます。
NavDisplay(
backStack = backStack,
onBack = { backStack.removeLastOrNull() },
entryDecorators = listOf(
rememberSaveableStateHolderNavEntryDecorator(),
rememberViewModelStoreNavEntryDecorator()
),
entryProvider = koinEntryProvider()
)ルート、またはそのフィールドをパラメータとして渡します。
class DetailViewModel(
@InjectedParam val route: DetailRoute,
private val repository: ItemRepository
) : ViewModel()
val detailModule = module {
viewModel<DetailViewModel>()
navigation<DetailRoute> { route ->
DetailScreen(viewModel = koinViewModel { parametersOf(route) })
}
}@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) })
}
}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>はmetadataマップを受け取り、それがNavEntryに渡されます。エントリごとの画面遷移(トランジション)や、リスト/詳細などのシーン戦略(Scene strategy)に使用します。
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())。メタデータのキーはKoinからではなく、Navigation 3やAdaptiveライブラリによって提供されるものです。
Navigation 2からの移行
| Navigation 2 | Koinを使用したNavigation 3 |
|---|---|
NavHost { composable(...) } 内の文字列または型指定されたルート | @Serializable なルートクラス |
NavHost 内の composable<Route> { ... } | Koinモジュール内の navigation<Route> { ... } |
NavHost(navController, startDestination) | NavDisplay(backStack, entryProvider = koinEntryProvider()) |
SavedStateHandle から引数を読み取り | ラムダに渡されるルートオブジェクト |
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) |
関連情報
- ComposeにおけるViewModel:
koinViewModel()とそのオーナー。 - Androidスコープ:
activityRetainedScopeとActivityスコープ。 - 注入パラメータ:
parametersOfと@InjectedParam。 - Koin for Compose: パッケージとKoinの開始。
- Navigation 3 recipes: GoogleによるNavigation 3自体のサンプル。
