Navigation 3
이 페이지에서는 Koin 모듈에서 Navigation 3 엔트리를 선언하고 이를 NavDisplay에 전달하는 방법을 설명합니다. 각 피처 모듈은 고유한 화면을 제공하며, 앱은 단일 엔트리 프로바이더(entry provider)를 통해 이 모든 화면을 수집합니다. 여기서는 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)모듈에서 라우트마다 하나의 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>는 라우트 타입으로 한정(qualified)된 정의로 저장됩니다. 람다는 Koin Scope를 수신 객체로 실행되므로 내부에서 get<T>()를 호출할 수 있으며, koinViewModel()과 같은 Composable 함수도 호출할 수 있습니다.
엔트리 프로바이더 구성하기
koinEntryProvider()는 현재 스코프의 모든 navigation<T> 엔트리를 수집하여 NavDisplay를 위한 단일 프로바이더로 만듭니다:
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) 시에도 유지됩니다:
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의 스토어를 사용하므로 동일한 라우트의 모든 엔트리가 단일 인스턴스를 공유하게 됩니다:
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>는 NavEntry로 전달되는 metadata 맵을 파라미터로 받습니다. 이를 엔트리별 화면 전환(transition)이나 리스트-상세(list-detail)와 같은 씬 전략(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에서 인자(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.navigation3 | Activity 또는 Fragment에서의 엔트리 프로바이더 (Android) |
관련 문서
- Compose에서의 ViewModel:
koinViewModel()및 소유자. - Android 스코프:
activityRetainedScope및 Activity 스코프. - 주입된 파라미터(Injected Parameters):
parametersOf및@InjectedParam. - Compose용 Koin: 패키지 구성 및 Koin 시작하기.
- Navigation 3 레시피(recipes): Google에서 제공하는 Navigation 3 자체 샘플.
