NavController — Wesen, Methoden und Navigationsverwaltung in Jetpack Compose

Was ist NavController in Jetpack Compose?

NavController ist eine Klasse aus der Navigation Compose-Bibliothek, die den Navigationscontroller für Compose-Anwendungen implementiert. NavController verwaltet den NavBackStackEntry-Stapel, wobei jeder Eintrag die Route, Argumente und den Bildschirmzustand enthält. Der Controller unterstützt grundlegende Navigationsoperationen: Übergang, Rückkehr, Ersetzung und Bereinigung.

Anders als beim View-System, wo die Navigation über FragmentManager oder Intent erfolgte, arbeitet NavController ausschließlich im Compose-Kontext. Der Back Stack wird als NavDestination-Graph und nicht als Fragment-Stapel gespeichert. Dies eliminiert den Overhead beim Erstellen und Zerstören von Fragmenten und vereinfacht das Testen — NavController kann über TestNavHostController mockiert werden.

NavController ist eng mit NavHost verbunden — einem Container, der den aktuellen Bildschirm aus dem Graphen rendert. Ohne NavHost kann NavController keine composable-Funktionen anzeigen, behält aber die Fähigkeit, den Stapel zu verwalten. In einer typischen Architektur wird NavController auf Activity- oder Haupt-composable-Ebene erstellt und über Parameter nach unten im Kompositionsbaum übergeben.

Laut Google hat NavController mehrere Hauptversionen durchlaufen. Version 2.8.0 führte Type-Safe Navigation ein, Version 2.9.0 führte Unterstützung für predictive back gesture (Android 14+) ein. Der Controller ist kompatibel mit Material3 Scaffold und BottomNavigation. Für Multimodul-Projekte wird NavController über DI (Hilt/Koin) oder Konstruktorparameter übergeben.

Erstellung und Konfiguration von NavController

NavController wird über die composable-Funktion rememberNavController() erstellt. Die Funktion gibt eine Instanz von NavHostController (eine Unterklasse von NavController) zurück, die an den Lebenszyklus des aktuellen composable gebunden ist. Beim Verlassen der Komposition wird der Controller gelöscht. Um den Controller während der Rekonfiguration zu erhalten, verwenden Sie rememberSaveable oder ViewModel.

@Composable
fun MyApp() {
    val navController = rememberNavController()
    NavHost(
        navController = navController,
        startDestination = "main"
    ) {
        composable("main") { MainScreen(navController) }
        composable("details") { DetailsScreen(navController) }
    }
}

Die NavController-Konfiguration umfasst: NavHostController (Haupt), TestNavHostController (Test) und ScopedNavController (Kind für verschachtelte Graphen). Für BottomNavigation sollte NavController für die gesamte App einheitlich sein — das Erstellen eines neuen Controllers in jedem Tab führt zu Stapelverlust. Um den Controller an verschachtelte Bildschirme zu übergeben, verwenden Sie einen Funktionsparameter anstelle von CompositionLocalProvider, um die Lesbarkeit zu erhalten.

Zum Testen der Navigation verwenden Sie TestNavHostController mit compose-test-rule. Der Controller ermöglicht das Festlegen der Startroute und die Überprüfung, ob navigate() den erwarteten Übergang ausgelöst hat. Das Testen von NavController erfordert keinen Emulator — es funktioniert mit den Semantics-Matchern von Compose Test.

Die navigate-Methode: Parameter und NavOptions

Die Methode navigate(route: String) ist der primäre Navigationsmechanismus in NavController. Sie akzeptiert eine Routenzeichenfolge, optionale NavOptions und Navigator.Extras. NavOptions steuern das Übergangsverhalten: launchSingleTop (Route nicht im Stapel duplizieren), popUpTo (Stapel bis zu einer Route leeren), restoreState (vorherigen Zustand wiederherstellen).

NavOptions werden über die Builder-Syntax festgelegt: NavOptionsBuilder. Hauptparameter: popUpTo (Route + inclusive/saveState), launchSingleTop (Boolean, true — keine Duplikate erstellen), restoreState (Zustand bei Rückkehr wiederherstellen). Ohne popUpTo fügt jeder navigate()-Aufruf einen Eintrag zum Stapel hinzu, was zur Ansammlung des Back Stacks und falschem Verhalten der Back-Taste führt.

navController.navigate("profile/42") {
    popUpTo("main") { saveState = true }
    launchSingleTop = true
    restoreState = true
}

Navigator.Extras ermöglicht das Übergeben zusätzlicher Daten, die nicht Teil der Route sind: gemeinsame Elemente für Animationen, Intent-Flags, Pac-Man-Bundle. Extras werden selten verwendet — hauptsächlich für die Integration mit Accompanist Animation oder benutzerdefinierten Navigators. Für die meisten Szenarien reichen eine Routenzeichenfolge und NavOptions aus.

popBackStack: Verwaltung von Rückkehr und Stapelbereinigung

popBackStack() ist die Methode zur Rückkehr zum vorherigen Bildschirm. Ohne Argumente entfernt sie den obersten Stapeleintrag und gibt true zurück, wenn die Entfernung erfolgreich war. Wenn der Stapel leer ist, gibt die Methode false zurück und die Activity wird geschlossen (ähnlich super.onBackPressed()).

Die überladene Version popBackStack(route: String, inclusive: Boolean) entfernt alle Einträge bis zur angegebenen Route. Wenn inclusive = true ist, wird auch die angegebene Route selbst entfernt. Die Methode gibt Boolean zurück — true, wenn Einträge gefunden und entfernt wurden. Die Version mit inclusive ist nützlich für Szenarien wie „Austritt zum Startbildschirm“ nach Autorisierung oder Bestellabschluss.

Zur Behandlung der systemischen Back-Taste (Hardware-Back-Button) verwenden Sie BackHandler aus Compose. BackHandler akzeptiert enabled und onBack — einen Callback, der beim Drücken aufgerufen wird. Für Android 14+ wird PredictiveBackGesture verwendet, das über NavController ab Version 2.9.0 integriert ist. Predictive back fügt eine Vorschau-Animation der Rückkehr hinzu.

SavedStateHandle: Erhaltung des Bildschirmzustands

SavedStateHandle ist ein Mechanismus zur Erhaltung des ViewModel-Zustands während Navigation und Rekonfiguration. NavController stellt automatisch SavedStateHandle für jeden NavBackStackEntry bereit. Über SavedStateHandle speichert ViewModel den Bildschirmzustand und stellt ihn bei Rückkehr wieder her (restoreState = true).

In Navigation Compose wird SavedStateHandle zusammen mit ViewModel verwendet: ViewModel wird über SavedStateHandle initialisiert, das von backStackEntry übergeben wird. Beim Navigieren zu einem anderen Bildschirm und Zurückkehren (mit restoreState) erhält ViewModel den gespeicherten Zustand, anstatt neu erstellt zu werden. Dies ist kritisch für Bildschirme mit Dateneingabe, Filtern oder Scrollen.

class ProfileViewModel(
    private val savedStateHandle: SavedStateHandle
) : ViewModel() {
    val userId: String = savedStateHandle.get<String>("userId") ?: ""
    var searchQuery by savedStateHandle.getStateFlow("search", "")
        .collectAsState()
}

SavedStateHandle unterstützt primitive Typen, String, Bundle und Parcelable. Für komplexe Objekte speichern Sie nur IDs und laden die vollständigen Daten aus dem Repository. Das Limit von SavedStateHandle beträgt etwa 1 MB — Überschreitung verursacht TransactionTooLargeException. Für große Datenmengen verwenden Sie Room oder DataStore anstelle der Speicherung im Handle.

Wichtig: SavedStateHandle erhält den Zustand nur, wenn restoreState = true in NavOptions verwendet wird. Wenn restoreState nicht angegeben ist, wird ViewModel bei Rückkehr mit Standardwerten neu erstellt. Für BottomNavigation-Umschaltung mit restoreState erhält NavController den Zustand jedes Tabs und stellt ihn bei erneuter Auswahl wieder her.

Beobachtung der aktuellen Route über currentBackStackEntryAsState

currentBackStackEntryAsState() ist eine Funktion, die State<NavBackStackEntry?> zurückgibt, das sich bei jeder Änderung der aktuellen Route aktualisiert. Dies ist der primäre Mechanismus zur UI-Synchronisation mit der Navigation: BottomNavigation hebt das aktive Element hervor, Toolbar aktualisiert den Titel, Drawer schließt bei Übergang.

Die Funktion arbeitet über snapshotFlow und collectAsState: Wenn sich der Back Stack ändert, komponiert Compose abonnierte Elemente neu. Wichtig: currentBackStackEntryAsState() aktualisiert erst nach Abschluss der Übergangsanimation. Für sofortige Aktualisierungen verwenden Sie currentDestination, das sich synchron mit navigate() ändert, aber keinen Zustand unterstützt.

val navBackStackEntry by navController.currentBackStackEntryAsState()
val currentRoute = navBackStackEntry?.destination?.route

Text(
    text = when (currentRoute) {
        "home" -> "Home"
        "profile" -> "Profile"
        else -> ""
    }
)

Um auf Argumente der aktuellen Route zuzugreifen, verwenden Sie navBackStackEntry?.arguments. Dies ist praktisch in BottomNavigation: selectedItem wird basierend auf currentRoute berechnet. Für Navigations-Debugging verwenden Sie NavController.addOnDestinationChangedListener(), das jeden Übergang protokolliert. In der Produktion vermeiden Sie Abonnements innerhalb vieler composables — erstellen Sie eine einzige Quelle in ViewModel und übergeben Sie State an die UI.