NavHost — was es ist, Aufbau des Graphen und Routen in Jetpack Compose

Was ist NavHost in Jetpack Compose?

NavHost ist eine composable-Funktion, die einen Container zum Anzeigen des aktuellen Navigationsbildschirms bereitstellt. NavHost nimmt einen NavController, startDestination und einen über Kotlin DSL erstellten Routengraphen entgegen. Wenn sich die aktuelle Route ändert, wechselt NavHost das angezeigte composable mit der angegebenen Animation.

NavHost fungiert als Bildschirmwechsler: er verfolgt den aktuellen NavBackStackEntry vom NavController und rendert den entsprechenden composable-Block. Jeder Bildschirm ist eine unabhängige composable-Funktion, die einen NavBackStackEntry mit Routenargumenten erhält. Alle Bildschirme existieren in einem einzigen Kompositionsbaum, aber NavHost zeigt jeweils nur einen an und blendet die anderen durch Animation aus.

Im Gegensatz zu FragmentManager erstellt NavHost keinen Fragment für jeden Bildschirm. Der gesamte Lebenszyklus wird über CompositionLifecycle verwaltet — composable-Funktionen haben kein onStart/onResume, daher werden LaunchedEffect und DisposableEffect für Seiteneffekte verwendet. NavHost abonniert automatisch den NavController und setzt die UI neu zusammen, wenn sich die Route ändert.

Laut Google ist NavHost seit Navigation 2.4.0 eine stabile API. Ab 2.8.0 unterstützt NavHost typsichere Navigation über Kotlin Serialization und ersetzt String-Routen durch Datenklassen. NavHost unterstützt auch verschachtelte Graphen, was eine modulbasierte Navigationsorganisation ermöglicht.

Erstellung von NavHost und Konfiguration von startDestination

NavHost wird mit zwei erforderlichen Parametern erstellt: navController (eine Instanz von NavHostController) und startDestination (der Routen-String des ersten Bildschirms). Der dritte Parameter ist ein Builder-Block, in dem alle Routen über composable(), navigation() und dialog() registriert werden.

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

startDestination ist die Route, die beim ersten Start von NavHost geöffnet wird. Wenn der Back-Stack leer ist, fügt NavHost automatisch startDestination zum Stack hinzu. Bei Rekonfiguration (Bildschirmdrehung) stellt NavHost die letzte Route aus savedState wieder her, nicht startDestination.

Für BottomNavigation ist startDestination eine der Routen des unteren Panels. Die verbleibenden Panel-Routen werden als separate composable-Einträge hinzugefügt. NavHost sollte innerhalb von Scaffold.content platziert werden — wo der Hauptinhalt der App angezeigt wird. NavHost belegt die gesamte verfügbare Höhe abzüglich TopAppBar und BottomNavigation.

Registrierung von Routen via composable

Die Funktion composable(route, arguments, deepLinks, enterTransition, exitTransition, content) registriert eine Route im NavHost-Graphen. Der Parameter route ist ein String, der den Pfad mit optionalen Platzhaltern in der Form {paramName} beschreibt. Der Platzhalter wird während der Navigation durch einen tatsächlichen Wert ersetzt.

Der content-Block von composable erhält einen NavBackStackEntry, aus dem die Argumente extrahiert werden. Die Bildschirm-composable-Funktion wird nur gerendert, wenn die aktuelle NavController-Route mit der Route übereinstimmt. Bei Nichtübereinstimmung wird das composable aus der Komposition entfernt, aber sein Zustand kann über rememberSaveable oder ViewModel mit SavedStateHandle erhalten bleiben.

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)
}

Die Anzahl der composable-Einträge innerhalb von NavHost kann von wenigen bis zu Hunderten reichen. Für große Anwendungen werden Routen über Module aufgeteilt und über verschachtelte Graphen verbunden. Jedes composable kann eigene Animationseinstellungen, Deep Links und Argumente haben.

Argumente und typisierte Routenparameter

Routenargumente werden über den Parameter arguments: List<NamedNavArgument> in composable() definiert. Jedes Argument wird über navArgument(name) { type; defaultValue } definiert. NavType bestimmt den Argumenttyp: StringType, IntType, LongType, FloatType, BoolType, ParcelableType und ReferenceType.

Argumente werden aus NavBackStackEntry über arguments?.getInt("id") extrahiert. Für erforderliche Argumente kann defaultValue weggelassen werden — NavType verwendet null. Für optionale Argumente muss defaultValue gesetzt werden, sonst wirft die Navigation eine Ausnahme, wenn der Parameter fehlt.

Seit Navigation 2.8.0 wird typsichere Navigation empfohlen: Definieren Sie eine versiegelte Klasse oder Datenklasse für Routen mit Kotlin Serialization. Verwenden Sie anstelle einer String-Route composable<RouteType> { backStackEntry -> }. Dies eliminiert Tippfehler in Routen und generiert automatisch NavType für Argumente. Zur Migration fügen Sie die Abhängigkeit navigation-compose-typesafe und das Kotlin Serialization Plugin hinzu.

Verschachtelte Navigationsgraphen

nested graphs — ein Mechanismus zum Gruppieren von Routen innerhalb von NavHost mit der Funktion navigation(route, startDestination). Ein verschachtelter Graph hat ein eigenes Routenpräfix und startDestination, und alle seine Routen sind über das Präfix zugänglich. Verschachtelte Graphen werden für modulare Architekturen verwendet, bei denen jedes Feature-Modul seinen eigenen Untergraphen registriert.

Vorteile verschachtelter Graphen: Routenisolierung innerhalb eines Moduls, ein einheitlicher Back-Stack für eine Gruppe von Bildschirmen und die Möglichkeit, über Präfix zu navigieren, ohne die interne Struktur offenzulegen. Beispielsweise enthält der Graph „aauth“ „aauth/login“ und „aauth/register“. Die Navigation ist entweder über die vollständige Route oder über Präfix mit Weiterleitung zu startDestination möglich.

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) }
    }
}

Verschachtelte Graphen unterstützen die Argumentübergabe auf Graphenebene: Im Routenpräfix deklarierte Parameter werden an alle internen Routen weitergegeben. Zum Löschen eines verschachtelten Graphen verwenden Sie popBackStack(route) — es entfernt alle internen Einträge. Verschachtelte Graphen haben keine Tiefenbeschränkung, aber für die Lesbarkeit werden nicht mehr als 3 Ebenen empfohlen.

Anpassung von Animationen und Übergängen

NavHost unterstützt Übergangsanimationen zwischen composable-Routen über die Parameter enterTransition, exitTransition, popEnterTransition und popExitTransition. Animationen werden einmal für NavHost festgelegt und gelten für alle Routen, oder einzeln für jedes composable. Standardmäßig sind Animationen deaktiviert.

Typische Konfiguration: enterTransition = slideInHorizontally(initialOffsetX = { it }) — der Bildschirm gleitet von rechts herein; exitTransition = slideOutHorizontally(targetOffsetX = { -it }) — der Bildschirm gleitet nach links hinaus. Für die Pop-Animation sind die Richtungen gespiegelt: Der Bildschirm gleitet von links herein und nach rechts hinaus. Für BottomNavigation wird fadeIn/fadeOut ohne Gleiten verwendet.

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 */ }

Benutzerdefinierte Animationen werden mit der Compose Animation API erstellt: AnimatedContentTransitionScope bietet Zugriff auf Containerabmessungen, Animationsfortschritt und Richtung. Für Shared-Element-Übergänge (ein Element bewegt sich nahtlos zu einem anderen Bildschirm) wird die Bibliothek Accompanist Navigation Animation oder eine benutzerdefinierte Implementierung über sharedElement Modifier benötigt. Laut Android Developers (2025) wird die Standard-Slide-Animation (Eingang von rechts, Ausgang nach links) in 80% der Android-Apps mit Navigation verwendet.