Oluşturma özelliğiyle gezinme

Gezinme bileşeni, Jetpack Compose uygulamaları için destek sağlar. Navigasyon bileşeninin altyapısından ve özelliklerinden yararlanarak bileşenler arasında gezinebilirsiniz.

Kurulum

Compose'u desteklemek için uygulama modülünüzün build.gradle dosyasında aşağıdaki bağımlılığı kullanın:

Groovy

dependencies {
    def nav_version = "2.8.4"

    implementation "androidx.navigation:navigation-compose:$nav_version"
}

Kotlin

dependencies {
    val nav_version = "2.8.4"

    implementation("androidx.navigation:navigation-compose:$nav_version")
}

Başlayın

Bir uygulamada gezinme özelliğini uygularken gezinme ana makinesi, grafiği ve denetleyicisi uygulayın. Daha fazla bilgi için Gezinme'ye genel bakış bölümüne bakın.

Oluşturma bölümünde NavController oluşturma hakkında bilgi edinmek için Gezinme denetleyicisi oluşturma başlıklı makalenin Oluşturma bölümüne bakın.

NavHost oluşturma

Oluştur'da NavHost oluşturma hakkında bilgi edinmek için Gezinme grafiğinizi tasarlama başlıklı makalenin Oluştur bölümüne bakın.

Bir Composable'a gitme hakkında bilgi edinmek için mimari belgelerindeki Bir hedefe gitme bölümüne bakın.

Birleştirilebilir hedefler arasında bağımsız değişkenler ile ilgili bilgi edinmek için Gezinme grafiğinizi tasarlama başlıklı makalenin Oluşturma bölümüne bakın.

Gezerken karmaşık verileri alma

Gezinirken karmaşık veri nesneleri iletmemek yerine, gezinme işlemleri gerçekleştirirken benzersiz tanımlayıcı veya başka bir kimlik biçimi gibi gerekli minimum bilgileri bağımsız değişken olarak iletmeniz önemle tavsiye edilir:

// Pass only the user ID when navigating to a new destination as argument
navController.navigate(Profile(id = "user1234"))

Karmaşık nesneler, veri katmanı gibi tek bir doğru kaynakta veri olarak depolanmalıdır. Gezinme işleminden sonra hedefinize ulaştığınızda, iletilen kimliği kullanarak gerekli bilgileri tek doğru kaynaktan yükleyebilirsiniz. Veri katmanına erişmekten sorumlu olan ViewModel öğenizdeki bağımsız değişkenleri almak için ViewModel öğesinin SavedStateHandle özelliğini kullanın:

class UserViewModel(
    savedStateHandle: SavedStateHandle,
    private val userInfoRepository: UserInfoRepository
) : ViewModel() {

    private val profile = savedStateHandle.toRoute<Profile>()

    // Fetch the relevant user information from the data layer,
    // ie. userInfoRepository, based on the passed userId argument
    private val userInfo: Flow<UserInfo> = userInfoRepository.getUserInfo(profile.id)

// …

}

Bu yaklaşım, yapılandırma değişiklikleri sırasında veri kaybını ve söz konusu nesne güncellenirken veya değiştirilirken ortaya çıkabilecek tutarsızlıkları önlemeye yardımcı olur.

Karmaşık verileri neden bağımsız değişken olarak iletmekten kaçınmanız gerektiğine dair daha ayrıntılı bir açıklama ve desteklenen bağımsız değişken türlerinin listesi için Hedefler arasında veri aktarma başlıklı makaleyi inceleyin.

Gezinme Oluşturma, composable() işlevinin bir parçası olarak tanımlanabilen derin bağlantıları da destekler. deepLinks parametresi, navDeepLink() yöntemi kullanılarak hızlıca oluşturulabilen NavDeepLink nesnelerinin bir listesini kabul eder:

@Serializable data class Profile(val id: String)
val uri = "https://www.example.com"

composable<Profile>(
  deepLinks = listOf(
    navDeepLink<Profile>(basePath = "$uri/profile")
  )
) { backStackEntry ->
  ProfileScreen(id = backStackEntry.toRoute<Profile>().id)
}

Bu derin bağlantılar, belirli bir URL'yi, işlemi veya mime türünü bir derlenebilir öğeyle ilişkilendirmenize olanak tanır. Bu derin bağlantılar varsayılan olarak harici uygulamalara gösterilmez. Bu derin bağlantıları harici olarak kullanılabilir hale getirmek için uygulamanızın manifest.xml dosyasına uygun <intent-filter> öğelerini eklemeniz gerekir. Önceki örnekteki derin bağlantıyı etkinleştirmek için manifest dosyasının <activity> öğesine aşağıdakileri eklemeniz gerekir:

<activity …>
  <intent-filter>
    ...
    <data android:scheme="https" android:host="www.example.com" />
  </intent-filter>
</activity>

Derin bağlantı başka bir uygulama tarafından tetiklendiğinde gezinme, otomatik olarak ilgili derlenebilir öğeye derin bağlantı oluşturur.

Bu derin bağlantılar, bir bileşenden uygun derin bağlantıya sahip bir PendingIntent oluşturmak için de kullanılabilir:

val id = "exampleId"
val context = LocalContext.current
val deepLinkIntent = Intent(
    Intent.ACTION_VIEW,
    "https://www.example.com/profile/$id".toUri(),
    context,
    MyActivity::class.java
)

val deepLinkPendingIntent: PendingIntent? = TaskStackBuilder.create(context).run {
    addNextIntentWithParentStack(deepLinkIntent)
    getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT)
}

Ardından, uygulamanızı derin bağlantı hedefinde açmak için bu deepLinkPendingIntent değerini diğer tüm PendingIntent değerleri gibi kullanabilirsiniz.

İç içe yerleştirilmiş gezinme

İç içe yerleştirilmiş gezinme grafikleri oluşturma hakkında bilgi edinmek için İç içe yerleştirilmiş grafikler başlıklı makaleyi inceleyin.

Alt gezinme çubuğuyla entegrasyon

NavController öğesini, birleştirilebilir hiyerarşinizde daha üst bir seviyede tanımlayarak gezinme menüsünü alt gezinme menüsü gibi diğer bileşenlere bağlayabilirsiniz. Bu sayede, alt çubuktaki simgeleri seçerek gezinebilirsiniz.

BottomNavigation ve BottomNavigationItem bileşenlerini kullanmak için Android uygulamanıza androidx.compose.material bağımlılığını ekleyin.

Groovy

dependencies {
    implementation "androidx.compose.material:material:1.7.5"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

dependencies {
    implementation("androidx.compose.material:material:1.7.5")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Alt gezinme çubuğundaki öğeleri gezinme grafiğinizdeki rotalara bağlamak için burada gösterilen TopLevelRoute gibi bir rota sınıfı ve simgesi olan bir sınıf tanımlamanız önerilir.

data class TopLevelRoute<T : Any>(val name: String, val route: T, val icon: ImageVector)

Ardından bu rotaları BottomNavigationItem tarafından kullanılabilecek bir listeye yerleştirin:

val topLevelRoutes = listOf(
   TopLevelRoute("Profile", Profile, Icons.Profile),
   TopLevelRoute("Friends", Friends, Icons.Friends)
)

BottomNavigation bileşeninizde currentBackStackEntryAsState() işlevini kullanarak mevcut NavBackStackEntry değerini alın. Bu giriş, mevcut NavDestination'e erişmenizi sağlar. NavDestination hiyerarşisini kullanarak iç içe yerleştirilmiş gezinme özelliğini kullandığınızda, her BottomNavigationItem öğesinin seçili durumu, öğenin yolu mevcut hedefin ve üst hedeflerinin yoluyla karşılaştırılarak belirlenebilir.

Öğenin rotası, onClick lambda'sını navigate çağrısına bağlamak için de kullanılır. Böylece öğeye dokunulduğunda ilgili öğeye gidilir. saveState ve restoreState işaretçileri kullanılarak, alt gezinme öğeleri arasında geçiş yaptığınızda ilgili öğenin durumu ve geri yığını doğru şekilde kaydedilir ve geri yüklenir.

val navController = rememberNavController()
Scaffold(
  bottomBar = {
    BottomNavigation {
      val navBackStackEntry by navController.currentBackStackEntryAsState()
      val currentDestination = navBackStackEntry?.destination
      topLevelRoutes.forEach { topLevelRoute ->
        BottomNavigationItem(
          icon = { Icon(topLevelRoute.icon, contentDescription = topLevelRoute.name) },
          label = { Text(topLevelRoute.name) },
          selected = currentDestination?.hierarchy?.any { it.hasRoute(topLevelRoute.route::class) } == true,
          onClick = {
            navController.navigate(topLevelRoute.route) {
              // Pop up to the start destination of the graph to
              // avoid building up a large stack of destinations
              // on the back stack as users select items
              popUpTo(navController.graph.findStartDestination().id) {
                saveState = true
              }
              // Avoid multiple copies of the same destination when
              // reselecting the same item
              launchSingleTop = true
              // Restore state when reselecting a previously selected item
              restoreState = true
            }
          }
        )
      }
    }
  }
) { innerPadding ->
  NavHost(navController, startDestination = Profile, Modifier.padding(innerPadding)) {
    composable<Profile> { ProfileScreen(...) }
    composable<Friends> { FriendsScreen(...) }
  }
}

Burada, navController durumunu NavHost işlevinden kaldırmak ve BottomNavigation bileşeniyle paylaşmak için NavController.currentBackStackEntryAsState() yönteminden yararlanıyorsunuz. Bu, BottomNavigation'ün otomatik olarak en güncel durumda olduğu anlamına gelir.

Birlikte çalışabilirlik

Gezinme bileşenini Oluştur ile kullanmak istiyorsanız iki seçeneğiniz vardır:

  • Gezinme bileşenini kullanarak fragmanlar için bir gezinme grafiği tanımlayın.
  • Oluştur hedeflerini kullanarak Oluştur'da NavHost içeren bir gezinme grafiği tanımlayın. Bu işlem yalnızca gezinme grafiğindeki tüm ekranlar kompozit ise mümkündür.

Bu nedenle, karma Oluşturma ve Görüntüleme uygulamaları için önerimiz, Parça tabanlı gezinme bileşenini kullanmanızdır. Bu sayede, görünüme dayalı ekranlar, oluşturma ekranları ve hem görünümü hem de oluşturma özelliğini kullanan ekranlar parçalarda tutulur. Her bir Fragment'in içeriği Oluştur'a eklendikten sonra, sonraki adım bu ekranların tümünü Gezinme Oluştur ile bağlamak ve tüm Fragment'leri kaldırmaktır.

Oluşturma kodu içindeki hedefleri değiştirmek için hiyerarşide herhangi bir bileşene iletilebilecek ve bileşen tarafından tetiklenebilecek etkinlikleri gösterirsiniz:

@Composable
fun MyScreen(onNavigate: (Int) -> Unit) {
    Button(onClick = { onNavigate(R.id.nav_profile) } { /* ... */ }
}

Parçanızda, NavController öğesini bulup hedefe giderek Oluştur ve parça tabanlı Gezinme bileşeni arasında köprü oluşturursunuz:

override fun onCreateView( /* ... */ ) {
    setContent {
        MyScreen(onNavigate = { dest -> findNavController().navigate(dest) })
    }
}

Alternatif olarak, NavController öğesini Oluşturma hiyerarşinizden aşağı aktarabilirsiniz. Ancak basit işlevler çok daha fazla yeniden kullanılabilir ve test edilebilir.

Test

Her bir derlenebilir öğeyi NavHost derlenebilir öğesinden ayrı olarak tek başına test etmek için gezinme kodunu derlenebilir hedeflerinizden ayırın.

Bu nedenle, navController'ü doğrudan herhangi bir bileşene değil, gezinme geri çağırma işlevlerini parametre olarak iletmeniz gerekir. Bu sayede, testlerde navController örneği gerektirmediğinden tüm bileşenlerinizin ayrı ayrı test edilmesi sağlanır.

composable lambda tarafından sağlanan dolaylı çağrı düzeyi, gezinme kodunuzu kompozit öğenin kendisinden ayırmanıza olanak tanır. Bu işlem iki şekilde çalışır:

  • Yalnızca ayrıştırılmış bağımsız değişkenleri composable öğenize iletin
  • Gezinmek için NavController yerine, composable tarafından tetiklenmesi gereken lambda'ları iletin.

Örneğin, giriş olarak userId alan ve kullanıcıların bir arkadaşın profil sayfasına gitmesine olanak tanıyan bir ProfileScreen bileşeninin imzası şu şekilde olabilir:

@Composable
fun ProfileScreen(
    userId: String,
    navigateToFriendProfile: (friendUserId: String) -> Unit
) {
 …
}

Bu sayede, ProfileScreen bileşeni Gezinme'den bağımsız olarak çalışır ve bağımsız olarak test edilebilir. composable lambda, gezinme API'leri ile bileşeniniz arasındaki boşluğu doldurmak için gereken minimum mantığı kapsar:

@Serializable data class Profile(id: String)

composable<Profile> { backStackEntry ->
    val profile = backStackEntry.toRoute<Profile>()
    ProfileScreen(userId = profile.id) { friendUserId ->
        navController.navigate(route = Profile(id = friendUserId))
    }
}

NavHost'yi, bileşenlerinize iletilen gezinme işlemlerini ve tek tek ekran bileşenlerinizi test ederek uygulama gezinme şartlarınızı kapsayan testler yazmanız önerilir.

NavHost

NavHost uygulamanızı test etmeye başlamak için aşağıdaki gezinme testi bağımlılığını ekleyin:

dependencies {
// ...
  androidTestImplementation "androidx.navigation:navigation-testing:$navigationVersion"
  // ...
}

Uygulamanızın NavHost öğesini, parametre olarak NavHostController kabul eden bir bileşene sarmalayın.

@Composable
fun AppNavHost(navController: NavHostController){
  NavHost(navController = navController){ ... }
}

Artık gezinme testi yapısını TestNavHostController bir örneğini ileterek AppNavHost ve NavHost içinde tanımlanan tüm gezinme mantığını test edebilirsiniz. Uygulamanızın ve NavHost'ün başlangıç hedefini doğrulayan bir kullanıcı arayüzü testi şöyle görünür:

class NavigationTest {

    @get:Rule
    val composeTestRule = createComposeRule()
    lateinit var navController: TestNavHostController

    @Before
    fun setupAppNavHost() {
        composeTestRule.setContent {
            navController = TestNavHostController(LocalContext.current)
            navController.navigatorProvider.addNavigator(ComposeNavigator())
            AppNavHost(navController = navController)
        }
    }

    // Unit test
    @Test
    fun appNavHost_verifyStartDestination() {
        composeTestRule
            .onNodeWithContentDescription("Start Screen")
            .assertIsDisplayed()
    }
}

Gezinme işlemlerini test etme

Kullanıcı arayüzü öğelerini tıklayıp görüntülenen hedefi doğrulayarak veya beklenen rotayı mevcut rotayla karşılaştırarak navigasyon uygulamanızı birden fazla şekilde test edebilirsiniz.

Uygulamanızın uygulamasını test etmek istediğiniz için kullanıcı arayüzündeki tıklamalar tercih edilir. Bunu, tek tek derlenebilir işlevlerle birlikte nasıl tek başına test edeceğinizi öğrenmek için Jetpack Compose'da test etme codelab'ine göz atın.

Ayrıca, navController'ın currentBackStackEntry özelliğini kullanarak mevcut rotayı beklenen rotayla karşılaştırarak iddialarınızı kontrol etmek için navController'i kullanabilirsiniz:

@Test
fun appNavHost_clickAllProfiles_navigateToProfiles() {
    composeTestRule.onNodeWithContentDescription("All Profiles")
        .performScrollTo()
        .performClick()

    assertTrue(navController.currentBackStackEntry?.destination?.hasRoute<Profile>() ?: false)
}

Compose testiyle ilgili temel bilgiler hakkında daha fazla bilgi için Compose düzeninizi test etme başlıklı makaleyi ve Jetpack Compose'da test etme codelab'ini inceleyin. Gezinme kodunun gelişmiş testi hakkında daha fazla bilgi edinmek için Gezinmeyi Test Etme kılavuzunu ziyaret edin.

Daha fazla bilgi

Jetpack Gezinme hakkında daha fazla bilgi edinmek için Gezinme bileşenini kullanmaya başlama başlıklı makaleyi inceleyin veya Jetpack Compose Gezinme kod laboratuvarını tamamlayın.

Uygulamanızın gezinme menüsünü farklı ekran boyutlarına, yönlere ve form faktörlerine uyum sağlayacak şekilde nasıl tasarlayacağınızı öğrenmek için Duyarlı kullanıcı arayüzleri için gezinme başlıklı makaleyi inceleyin.

Modüler bir uygulamada iç içe yerleştirilmiş grafikler ve alt gezinme çubuğu entegrasyonu gibi kavramlar da dahil olmak üzere daha gelişmiş bir Compose gezinme uygulaması hakkında bilgi edinmek için GitHub'daki Now in Android uygulamasına göz atın.

Örnekler