NavHost — mi ez, gráf felépítése és útvonalak Jetpack Compose-ban

Mi az a NavHost Jetpack Compose-ban?

NavHost egy composable függvény, amely konténert biztosít az aktuális navigációs képernyő megjelenítéséhez. A NavHost elfogad egy NavController-t, startDestination-t és a Kotlin DSL segítségével felépített útvonalgráfot. Amikor az aktuális útvonal megváltozik, a NavHost átkapcsolja a megjelenített composable-t a megadott animációval.

A NavHost képernyőkapcsolóként működik: követi az aktuális NavBackStackEntry-t a NavController-ből, és megjeleníti a megfelelő composable blokkot. Minden képernyő egy független composable függvény, amely NavBackStackEntry-t kap az útvonal argumentumaival. Az összes képernyő egyetlen kompozíciós fában létezik, de a NavHost egyszerre csak egyet jelenít meg, a többit animációval elrejtve.

A FragmentManager-rel ellentétben a NavHost nem hoz létre Fragment-et minden képernyőhöz. A teljes életciklus a CompositionLifecycle-en keresztül történik — a composable függvényeknek nincs onStart/onResume-jük, ezért a mellékhatásokhoz LaunchedEffect és DisposableEffect használatos. A NavHost automatikusan feliratkozik a NavController-re, és útvonalváltáskor újrakomponálja a UI-t.

A Google szerint a NavHost stabil API a Navigation 2.4.0 verzió óta. A 2.8.0-tól kezdve a NavHost támogatja a Type-Safe Navigation-t Kotlin Serialization segítségével, ami a string route-okat data osztályokkal váltja fel. A NavHost a beágyazott gráfokat is támogatja, lehetővé téve a navigáció modulonkénti szervezését.

NavHost létrehozása és startDestination konfigurálása

A NavHost két kötelező paraméterrel jön létre: navController (NavHostController példány) és startDestination (az első képernyő útvonalának string-je). A harmadik paraméter a builder blokk, amelyben az összes útvonal regisztrálásra kerül a composable(), navigation() és dialog() segítségével.

@Composable
fun AppNavHost(navController: NavHostController) {
    NavHost(
        navController = navController,
        startDestination = "home"
    ) {
        composable("home") { HomeScreen(navController) }
        composable("settings") { SettingsScreen(navController) }
    }
}

A startDestination az az útvonal, amely a NavHost első indításakor megnyílik. Ha a back stack üres, a NavHost automatikusan hozzáadja a startDestination-t a veremhez. Rekonfigurációkor (képernyőelforgatás) a NavHost az utolsó útvonalat állítja vissza a savedState-ből, nem a startDestination-t.

A BottomNavigation esetében a startDestination az alsó panel egyik útvonala. A panel többi útvonala külön composable bejegyzésként kerül hozzáadásra. A NavHost-t a Scaffold.content-en belül kell elhelyezni — ahol az alkalmazás fő tartalma megjelenik. A NavHost a Teljes rendelkezésre álló magasságot elfoglalja, mínusz a TopAppBar és a BottomNavigation.

Útvonalak regisztrálása composable segítségével

A composable(route, arguments, deepLinks, enterTransition, exitTransition, content) függvény regisztrál egy útvonalat a NavHost gráfban. A route paraméter egy string, amely az elérési utat írja le opcionális {paramName} formátumú helyőrzőkkel. A helyőrző navigációkor konkrét értékre cserélődik.

A content blokk NavBackStackEntry-t kap, amelyből az argumentumok kinyerhetők. A képernyő composable függvénye csak akkor jelenik meg, ha a NavController aktuális útvonala megegyezik a route-tal. Eltérés esetén a composable eltávolításra kerül a kompozícióból, de állapota menthető a rememberSaveable vagy ViewModel SavedStateHandle segítségével.

composable(
    route = "article/{articleId}",
    arguments = listOf(navArgument("articleId") {
        type = NavType.IntType
        defaultValue = 0
    }),
    deepLinks = listOf(navDeepLink { uriPattern = "https://app.example/article/{articleId}" })
) { backStackEntry ->
    val articleId = backStackEntry.arguments?.getInt("articleId") ?: 0
    ArticleScreen(articleId = articleId)
}

A NavHost-on belüli composable bejegyzések száma bármennyi lehet — néhánytól a százakig. Nagy alkalmazások esetén az útvonalak modulonként vannak felosztva és beágyazott gráfokon keresztül csatlakoztatva. Minden composable rendelkezhet saját animációs, deep link és argumentum beállításokkal.

Argumentumok és tipizált útvonalparaméterek

Az útvonal argumentumai a arguments: List<NamedNavArgument> paraméterrel definiálhatók a composable()-ban. Minden argumentum a navArgument(name) { type; defaultValue } segítségével adható meg. A NavType határozza meg az argumentum típusát: StringType, IntType, LongType, FloatType, BoolType, ParcelableType és ReferenceType.

Az argumentumok a NavBackStackEntry-ből nyerhetők ki a arguments?.getInt("id") segítségével. Kötelező argumentumok esetén a defaultValue elhagyható — a NavType null-t fog használni. Opcionális argumentumoknál a defaultValue kötelező, különben a navigáció kivételt dob a paraméter hiányakor.

A Navigation 2.8.0 verziótól kezdve ajánlott a Type-Safe Navigation: definiáljon sealed class vagy data class útvonalakat Kotlin Serialization segítségével. String route helyett használja a composable<RouteType> { backStackEntry -> } formát. Ez kiküszöböli a gépelési hibákat a route-ban, és automatikusan generál NavType-ot az argumentumokhoz. A migrációhoz adja hozzá a navigation-compose-typesafe függőséget és a Kotlin Serialization plugint.

Beágyazott navigációs gráfok

nested graphs — az útvonalak csoportosításának mechanizmusa a NavHost-on belül a navigation(route, startDestination) függvény segítségével. A beágyazott gráfnak saját route előtagja és startDestination-ja van, és minden útvonala az előtagon keresztül érhető el. A nested graphs moduláris architektúrához használatos, ahol minden feature modul regisztrálja a saját algráfját.

A beágyazott gráfok előnyei: az útvonalak elkülönítése a modulon belül, egységes back stack a képernyőcsoport számára, navigációs lehetőség előtag alapján a belső szerkezet felfedése nélkül. Például az „auth" gráf tartalmazza az „auth/login" és „auth/register" útvonalakat. A navigáció lehetséges a teljes útvonalon, valamint az előtagon keresztül átirányítással a startDestination-ra.

NavHost(navController = navController, startDestination = "main") {
    composable("main") { MainScreen(navController) }
    navigation(
        route = "auth",
        startDestination = "auth/login"
    ) {
        composable("auth/login") { LoginScreen(navController) }
        composable("auth/register") { RegisterScreen(navController) }
    }
}

A nested graphs támogatják az argumentumok továbbítását gráf szinten: a gráf route-jában deklarált paraméterek az összes belső útvonalra továbbítódnak. A beágyazott gráf törléséhez használja a popBackStack(route) függvényt — ez eltávolítja az összes belső bejegyzést. A beágyazott gráfoknak nincs mélységkorlátja, de az olvashatóság érdekében legfeljebb 3 szint ajánlott.

Animáció és átmenetek testreszabása

A NavHost támogatja az átmeneti animációt a composable útvonalak között a enterTransition, exitTransition, popEnterTransition és popExitTransition paraméterek segítségével. Az animációk egyszer definiálhatók a NavHost számára, és az összes útvonalra alkalmazódnak, vagy egyedileg minden composable-ra. Alapértelmezés szerint az animáció ki van kapcsolva.

Tipikus konfiguráció: enterTransition = slideInHorizontally(initialOffsetX = { it }) — a képernyő jobbról érkezik; exitTransition = slideOutHorizontally(targetOffsetX = { -it }) — a képernyő balra távozik. Pop animáció esetén az irányok tükrözöttek: a képernyő balról érkezik és jobbra távozik. A BottomNavigation esetében fadeIn/fadeOut használatos slide nélkül.

NavHost(
    navController = navController,
    startDestination = "home",
    enterTransition = { slideInHorizontally(initialOffsetX = { it }) + fadeIn() },
    exitTransition = { slideOutHorizontally(targetOffsetX = { -it }) + fadeOut() },
    popEnterTransition = { slideInHorizontally(initialOffsetX = { -it }) + fadeIn() },
    popExitTransition = { slideOutHorizontally(targetOffsetX = { it }) + fadeOut() }
) { /* composable routes */ }

Egyedi animációk a Compose Animation API segítségével hozhatók létre: az AnimatedContentTransitionScope hozzáférést biztosít a konténer méreteihez, az animáció előrehaladásához és az irányhoz. A shared element transition (egy elem zökkenőmentes átmenete egy másik képernyőre) esetén az Accompanist Navigation Animation könyvtár vagy egyedi implementáció szükséges a sharedElement Modifier segítségével. Az Android Developers (2025) szerint az alapértelmezett slide animáció (jobbról érkezés, balra távozás) a navigációval rendelkező Android alkalmazások 80%-ában használatos.