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)

モジュール内でルートごとに1つのnavigation<T> { }を宣言します。ラムダはルートを受け取る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>はルート型によって修飾された定義として保存されます。ラムダはKoinのScopeをレシーバーとして実行されるため、その中でget<T>()を呼び出したり、koinViewModel()などのComposable関数を呼び出したりできます。

エントリプロバイダーの構築 ​

koinEntryProvider()は、現在のスコープのすべてのnavigation<T>エントリを収集し、NavDisplay用の1つのプロバイダーにまとめます。

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が型指定されている場合は独自のルート型になります(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)をまたいで維持されます。

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 Scopesを参照してください。

エントリ用のViewModel ​

ViewModelのスコープをそのエントリに限定するには、NavDisplayにViewModel storeデコレーターを追加します。これがない場合、koinViewModel()はActivityのストアを使用するため、同じルートのすべてのエントリで1つのインスタンスが共有されます。

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>はmetadataマップを受け取り、それがNavEntryに渡されます。エントリごとの画面遷移(トランジション)や、リスト/詳細などのシーン戦略(Scene strategy)に使用します。

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())。メタデータのキーはKoinからではなく、Navigation 3やAdaptiveライブラリによって提供されるものです。

Navigation 2からの移行 ​

Navigation 2Koinを使用した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.navigation3ActivityまたはFragmentからのエントリプロバイダー(Android)