NavHost — nedir, Jetpack Compose'da navigasyon grafiği ve rota oluşturma

Jetpack Compose'da NavHost nedir?

NavHost, geçerli navigasyon ekranını görüntülemek için bir kapsayıcı sağlayan bir composable işlevidir. NavHost, bir NavController, startDestination ve Kotlin DSL ile oluşturulmuş bir rota grafiği alır. Geçerli rota değiştiğinde, NavHost belirtilen animasyonla görüntülenen composable'ı değiştirir.

NavHost bir ekran değiştirici olarak çalışır: NavController'dan geçerli NavBackStackEntry'yi izler ve ilgili composable bloğunu render eder. Her ekran, rota argümanlarıyla bir NavBackStackEntry alan bağımsız bir composable işlevidir. Tüm ekranlar tek bir kompozisyon ağacında bulunur, ancak NavHost aynı anda yalnızca birini gösterir, diğerlerini animasyonla gizler.

FragmentManager'ın aksine, NavHost her ekran için bir Fragment oluşturmaz. Tüm yaşam döngüsü CompositionLifecycle aracılığıyla yönetilir — composable işlevlerinde onStart/onResume yoktur, bu nedenle yan etkiler için LaunchedEffect ve DisposableEffect kullanılır. NavHost otomatik olarak NavController'a abone olur ve rota değiştiğinde UI'ı yeniden oluşturur.

Google'a göre, NavHost Navigation 2.4.0'dan itibaren kararlı bir API'dir. 2.8.0'dan itibaren NavHost, Kotlin Serialization aracılığıyla Tür Güvenli Navigasyonu destekler ve dize rotalarını veri sınıflarıyla değiştirir. NavHost ayrıca iç içe grafikleri destekleyerek modül tabanlı navigasyon düzenlemesine olanak tanır.

NavHost oluşturma ve startDestination yapılandırma

NavHost iki zorunlu parametreyle oluşturulur: navController (bir NavHostController örneği) ve startDestination (ilk ekranın rota dizesi). Üçüncü parametre, composable(), navigation() ve dialog() aracılığıyla tüm rotaların kaydedildiği bir oluşturucu bloğudur.

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

startDestination, NavHost ilk başlatıldığında açılan rotadır. Geri yığını boşsa, NavHost otomatik olarak startDestination'ı yığına ekler. Yeniden yapılandırmada (ekran döndürme), NavHost savedState'den son rotayı geri yükler, startDestination'ı değil.

BottomNavigation için startDestination, alt panel rotalarından biridir. Kalan panel rotaları ayrı composable girişleri olarak eklenir. NavHost, Scaffold.content içine yerleştirilmelidir — ana uygulama içeriğinin görüntülendiği yer. NavHost, TopAppBar ve BottomNavigation hariç mevcut tüm yüksekliği kaplar.

Composable ile rota kaydetme

composable(route, arguments, deepLinks, enterTransition, exitTransition, content) işlevi, NavHost grafiğinde bir rota kaydeder. route parametresi, {paramName} biçiminde isteğe bağlı yer tutucularla yolu tanımlayan bir dizedir. Yer tutucu, navigasyon sırasında gerçek bir değerle değiştirilir.

Composable'ın content bloğu, argümanların çıkarıldığı bir NavBackStackEntry alır. Ekran composable işlevi, yalnızca geçerli NavController rotası rotayla eşleştiğinde render edilir. Eşleşmezse, composable kompozisyondan kaldırılır, ancak durumu rememberSaveable veya SavedStateHandle ile ViewModel aracılığıyla korunabilir.

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

NavHost içindeki composable girişlerinin sayısı birkaçtan yüzlere kadar değişebilir. Büyük uygulamalar için rotalar modüller arasında bölünür ve iç içe grafikler aracılığıyla bağlanır. Her composable'ın kendi animasyon ayarları, derin bağlantıları ve argümanları olabilir.

Argümanlar ve tür belirtilmiş rota parametreleri

Rota argümanları, composable() içindeki arguments: List<NamedNavArgument> parametresi aracılığıyla tanımlanır. Her argüman navArgument(name) { type; defaultValue } aracılığıyla tanımlanır. NavType, argüman türünü belirler: StringType, IntType, LongType, FloatType, BoolType, ParcelableType ve ReferenceType.

Argümanlar, arguments?.getInt("id") aracılığıyla NavBackStackEntry'den çıkarılır. Zorunlu argümanlar için defaultValue atlanabilir — NavType null kullanır. İsteğe bağlı argümanlar için defaultValue ayarlanmalıdır, aksi takdirde parametre eksikse navigasyon bir istisna oluşturur.

Navigation 2.8.0'dan itibaren, Tür Güvenli Navigasyon önerilir: Kotlin Serialization ile rotalar için bir sealed class veya data class tanımlayın. Bir dize rotası yerine, composable<RouteType> { backStackEntry -> } kullanın. Bu, rotalardaki yazım hatalarını ortadan kaldırır ve argümanlar için otomatik olarak NavType oluşturur. Geçiş yapmak için, navigation-compose-typesafe bağımlılığını ve Kotlin Serialization eklentisini ekleyin.

İç içe navigasyon grafikleri

nested graphs — navigation(route, startDestination) işlevini kullanarak NavHost içinde rotaları gruplama mekanizması. İç içe bir grafiğin kendi rota öneki ve startDestination'ı vardır ve tüm rotalarına önek aracılığıyla erişilebilir. İç içe grafikler, her özellik modülünün kendi alt grafiğini kaydettiği modüler mimari için kullanılır.

İç içe grafiklerin faydaları: bir modül içinde rota izolasyonu, bir ekran grubu için birleşik bir geri yığını ve iç yapıyı ifşa etmeden önekle gezinme yeteneği. Örneğin, "auth" grafiği "auth/login" ve "auth/register" içerir. Gezinme, tam rota üzerinden veya startDestination'a yönlendirmeyle önek üzerinden mümkündür.

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

İç içe grafikler, grafik düzeyinde argüman iletimini destekler: grafiğin rotasında bildirilen parametreler tüm iç rotalara iletilir. İç içe bir grafiği temizlemek için popBackStack(route) kullanın — tüm iç girişleri kaldıracaktır. İç içe grafiklerin derinlik sınırı yoktur, ancak okunabilirlik için 3 seviyeden fazlası önerilmez.

Animasyon ve geçiş özelleştirme

NavHost, enterTransition, exitTransition, popEnterTransition ve popExitTransition parametreleri aracılığıyla composable rotalar arasında geçiş animasyonlarını destekler. Animasyonlar NavHost için bir kez ayarlanır ve tüm rotalara uygulanır veya her composable için ayrı ayrı uygulanır. Varsayılan olarak, animasyonlar devre dışıdır.

Tipik yapılandırma: enterTransition = slideInHorizontally(initialOffsetX = { it }) — ekran sağdan içeri kayar; exitTransition = slideOutHorizontally(targetOffsetX = { -it }) — ekran sola dışarı kayar. Pop animasyonu için yönler tersine çevrilir: ekran soldan içeri kayar ve sağa dışarı kayar. BottomNavigation için, kaydırmasız fadeIn/fadeOut kullanılır.

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

Özel animasyonlar Compose Animation API kullanılarak oluşturulur: AnimatedContentTransitionScope, kapsayıcı boyutlarına, animasyon ilerlemesine ve yöne erişim sağlar. Paylaşılan öğe geçişleri için (bir öğenin başka bir ekrana sorunsuzca hareket etmesi), Accompanist Navigation Animation kitaplığı veya sharedElement Modifier aracılığıyla özel uygulama gereklidir. Android Developers (2025)'e göre, varsayılan kaydırma animasyonu (sağdan giriş, sola çıkış) navigasyonlu Android uygulamalarının %80'inde kullanılır.