Skip to content

Navigation 3 ​

이 페이지에서는 Koin 모듈에서 Navigation 3 엔트리를 선언하고 이를 NavDisplay에 전달하는 방법을 설명합니다. 각 피처 모듈은 고유한 화면을 제공하며, 앱은 단일 엔트리 프로바이더(entry provider)를 통해 이 모든 화면을 수집합니다. 여기서는 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> { }를 선언하세요. 람다는 라우트를 수신하는 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>는 라우트 타입으로 한정(qualified)된 정의로 저장됩니다. 람다는 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에 타입이 지정된 경우(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의 두 가지 확장 함수를 통해 Activity 또는 Fragment 스코프에서 프로바이더를 빌드할 수 있습니다:

함수동작
entryProvider<T>()지연 위임 프로퍼티(Lazy delegate): val provider by entryProvider<Any>()
getEntryProvider<T>()프로바이더를 즉시 빌드

이 함수들은 컴포넌트의 Koin 스코프에서 확인(resolve)됩니다. 컴포넌트가 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 스코프를 참고하세요.

엔트리를 위한 ViewModel ​

ViewModel의 범위를 엔트리로 한정하려면 NavDisplay에 ViewModel 스토어 데코레이터를 추가하세요. 데코레이터가 없으면 koinViewModel()은 Activity의 스토어를 사용하므로 동일한 라우트의 모든 엔트리가 단일 인스턴스를 공유하게 됩니다:

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 맵을 파라미터로 받습니다. 이를 엔트리별 화면 전환(transition)이나 리스트-상세(list-detail)와 같은 씬 전략(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에서 인자(arguments)를 읽음람다로 전달되는 라우트 객체

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)