Oluşturma özelliğiyle gezinme

Navigation bileşeni, Jetpack Compose uygulamaları için destek sağlar. Navigation bileşeninin altyapısından ve özelliklerinden yararlanırken composable'lar arasında gezinebilirsiniz.

Compose için özel olarak oluşturulan en yeni alfa gezinme kitaplığı hakkında bilgi edinmek için Navigation 3 dokümanlarına bakın.

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.9.5"

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

Kotlin

dependencies {
    val nav_version = "2.9.5"

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

Başlayın

Bir uygulamada gezinme işlevini uygularken gezinme ana makinesi, grafik ve denetleyici uygulayın. Daha fazla bilgi için Gezinmeye genel bakış konusuna 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şturma bölümünde NavHost oluşturma hakkında bilgi için Gezinme grafiğinizi tasarlama başlıklı makalenin Oluşturma bölümüne bakın.

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

Composable hedefler arasında bağımsız değişkenleri iletme hakkında bilgi edinmek için Gezinme grafiğinizi tasarlama başlıklı makalenin Compose bölümüne bakın.

Navigasyon sırasında karmaşık verileri alma

Gezinirken karmaşık veri nesnelerini iletmemeniz, bunun yerine gezinme işlemleri gerçekleştirirken benzersiz bir tanımlayıcı veya başka bir kimlik biçimi gibi gerekli minimum bilgiyi 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 kaynağında veri olarak depolanmalıdır. Gezindikten sonra hedefinize ulaştığınızda, iletilen kimliği kullanarak tek doğru kaynakta bulunan gerekli bilgileri yükleyebilirsiniz. Veri katmanına erişmekten sorumlu ViewModel işlevinizdeki bağımsız değişkenleri almak için ViewModel işlevinin SavedStateHandle işlevini 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 tutarsızlıkları önlemeye yardımcı olur.

Karmaşık verileri neden bağımsız değişken olarak iletmemeniz gerektiğiyle ilgili daha ayrıntılı açıklama ve desteklenen bağımsız değişken türlerinin listesi için Hedefler arasında veri iletme başlıklı makaleyi inceleyin.

Navigation Compose, composable() işlevinin bir parçası olarak da tanımlanabilen derin bağlantıları destekler. deepLinks parametresi, navDeepLink() yöntemiyle hızlıca oluşturulabilen NavDeepLink nesnelerinin 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 composable ile ilişkilendirmenize olanak tanır. Varsayılan olarak, bu derin bağlantılar 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. Yukarıdaki örnekte derin bağlantıyı etkinleştirmek için manifest dosyasının <activity> öğesinin içine 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, bu composable'a otomatik olarak derin bağlantı oluşturur.

Aynı derin bağlantılar, birleştirilebilir öğelerden uygun derin bağlantı ile 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 öğesini diğer PendingIntent öğeleri gibi kullanabilirsiniz.

İç İçe Gezinme

İç içe yerleştirilmiş gezinme grafikleri oluşturma hakkında bilgi için İç içe yerleştirilmiş grafikler başlıklı makaleye bakın.

Uyarlanabilir bir alt gezinme çubuğu ve gezinme rayı oluşturma

NavigationSuiteScaffold, uygulamanızın içinde oluşturulduğu WindowSizeClass'a göre uygun gezinme kullanıcı arayüzünü gösterir. Kompakt ekranlarda NavigationSuiteScaffold simgesiyle alt gezinme çubuğu gösterilir. Genişletilmiş ekranlarda ise bunun yerine gezinme rayı gösterilir.

Daha fazla bilgi için Uyarlanabilir gezinme oluşturma başlıklı makaleyi inceleyin.

Birlikte çalışabilirlik

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

  • Parçalar için Gezinme bileşeniyle bir gezinme grafiği tanımlayın.
  • Compose hedeflerini kullanarak Compose'da NavHost ile bir gezinme grafiği tanımlayın. Bu yalnızca gezinme grafiğindeki tüm ekranlar composable ise mümkündür.

Bu nedenle, Compose ve View'ları karışık kullanan uygulamalar için Fragment tabanlı gezinme bileşeninin kullanılması önerilir. Daha sonra parçalar, View tabanlı ekranları, Compose ekranlarını ve hem View hem de Compose kullanan ekranları tutar. Her bir Fragment'ın içeriği Compose'a aktarıldıktan sonraki adım, bu ekranların tümünü Navigation Compose ile bağlamak ve tüm Fragment'ları kaldırmaktır.

Compose kodunun içindeki hedefleri değiştirmek için hiyerarşideki herhangi bir composable'a iletilebilen ve bu composable tarafından tetiklenebilen etkinlikleri kullanıma sunarsınız:

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

Parçanızda, NavController öğesini bulup hedefe giderek Compose ile parçaya dayalı Navigation bileşeni arasında köprü oluşturursunuz:

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

Alternatif olarak, NavController öğesini Compose hiyerarşinizde iletebilirsiniz. Ancak basit işlevleri kullanıma sunmak çok daha fazla yeniden kullanılabilir ve test edilebilir.

Test

Her bir composable'ın NavHost composable'dan ayrı olarak izole bir şekilde test edilmesini sağlamak için gezinme kodunu composable hedeflerinizden ayırın.

Bu nedenle, navController doğrudan herhangi bir composable'a iletmemeli, bunun yerine gezinme geri çağırmalarını parametre olarak iletmelisiniz. Bu sayede, testlerde navController örneği gerektirmediğinden tüm composable'larınız ayrı ayrı test edilebilir.

composable lambda'nın sağladığı dolaylılık düzeyi, gezinme kodunuzu composable'dan ayırmanıza olanak tanır. Bu özellik iki yönde çalışır:

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

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

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

Bu sayede, ProfileScreen composable'ı Navigation'dan bağımsız olarak çalışır ve bağımsız olarak test edilebilir. composable lambda'sı, Navigation API'leri ile composable'ınız 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, composable'larınıza iletilen gezinme işlemleri ve ayrı ekran composable'larınızı test ederek uygulama gezinme şartlarınızı karşılayan testler yazmanız önerilir.

NavHost test ediliyor

NavHost 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 composable içine alın.

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

Artık gezinme testi yapay nesnesinin bir örneğini TestNavHostController ileterek AppNavHost ve NavHost içinde tanımlanan tüm gezinme mantığını test edebilirsiniz. Uygulamanızın başlangıç hedefini ve NavHost öğesini doğrulayan bir kullanıcı arayüzü testi şu şekilde 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ıklayarak ve ardından gösterilen hedefi doğrulayarak veya beklenen rotayı mevcut rotayla karşılaştırarak gezinme uygulamanızı birden fazla şekilde test edebilirsiniz.

Uygulamanızın somut uygulamasını test etmek istediğiniz için kullanıcı arayüzündeki tıklamalar tercih edilir. Bunu ayrı ayrı composable işlevlerle birlikte nasıl test edeceğinizi öğrenmek için Jetpack Compose'da Test adlı codelab'e göz atın.

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

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

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

Compose'da test etmenin temelleri hakkında daha fazla bilgi için Compose düzeninizi test etme 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 Navigation hakkında daha fazla bilgi edinmek için Navigation bileşenini kullanmaya başlama başlıklı makaleyi inceleyin veya Jetpack Compose Navigation codelab'ini tamamlayın.

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

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

Örnekler