Membuka tujuan

Komponen Navigation memberikan cara yang mudah dan umum untuk menavigasi ke tujuan. Antarmuka ini mendukung berbagai konteks dan framework UI. Misalnya, Anda dapat menggunakan komponen Navigation dengan Compose, tampilan, fragmen, aktivitas, dan bahkan framework UI kustom.

Panduan ini menjelaskan cara menggunakan komponen Navigation untuk menavigasi ke tujuan dalam berbagai konteks.

Menggunakan NavController

Jenis kunci yang Anda gunakan untuk berpindah antar-tujuan adalah NavController. Lihat Membuat pengontrol navigasi untuk informasi selengkapnya tentang class itu sendiri dan cara membuat instance-nya. Panduan ini menjelaskan cara menggunakannya.

Terlepas dari framework UI yang Anda gunakan, ada satu fungsi yang dapat Anda gunakan untuk menavigasi ke tujuan: NavController.navigate().

Ada banyak overload yang tersedia untuk navigate(). Overload yang harus Anda pilih sesuai dengan konteks yang tepat. Misalnya, Anda harus menggunakan satu overload saat menavigasi ke composable dan overload lain saat menavigasi ke tampilan.

Bagian berikut menguraikan beberapa overload navigate() utama yang dapat Anda gunakan.

Menavigasi ke komponen

Untuk menavigasi ke composable, Anda harus menggunakan NavController.navigate<T>. Dengan overload ini, navigate() akan menggunakan satu argumen route yang Anda meneruskan suatu jenis. Argumen ini berfungsi sebagai kunci ke tujuan.

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

Untuk menavigasi ke composable di grafik navigasi, tentukan terlebih dahulu NavGraph sedemikian rupa sehingga setiap tujuan sesuai dengan satu jenis. Sebagai composable, Anda melakukannya dengan fungsi composable().

Mengekspos peristiwa dari composable Anda

Saat fungsi composable perlu menavigasi ke layar baru, Anda tidak boleh meneruskan referensi ke NavController agar dapat memanggil navigate() secara langsung. Menurut prinsip Aliran Data Searah (UDF), composable harus mengekspos peristiwa yang ditangani NavController.

Lebih jelasnya, composable Anda harus memiliki parameter jenis () -> Unit. Saat Anda menambahkan tujuan ke NavHost dengan fungsi composable(), teruskan composable Anda ke NavController.navigate().

Lihat subbagian berikut untuk contohnya.

Contoh

Sebagai demonstrasi bagian sebelumnya, amati poin-poin ini dalam cuplikan berikut:

  1. Setiap tujuan dalam grafik dibuat menggunakan rute, yang merupakan objek atau class yang dapat diserialisasi, yang mendeskripsikan data yang diperlukan tujuan.
  2. Composable MyAppNavHost menyimpan instance NavController.
  3. Dengan demikian, panggilan ke navigate() harus terjadi di sana, bukan di composable yang lebih rendah seperti ProfileScreen.
  4. ProfileScreen berisi tombol yang mengarahkan pengguna ke FriendsList saat diklik. Namun, tombol itu tidak memanggil navigate() sendiri.
  5. Sebagai gantinya, tombol itu memanggil fungsi yang ditampilkan sebagai parameter onNavigateToFriends.
  6. Saat MyAppNavHost menambahkan ProfileScreen ke grafik navigasi, untuk onNavigateToFriends, ini akan meneruskan lambda yang memanggil navigate(route = FriendsList).
  7. Hal ini memastikan bahwa saat pengguna menekan tombol ProfileScreen, semuanya akan menavigasi dengan benar ke FriendsListScreen.
@Serializable
object Profile
@Serializable
object FriendsList

@Composable
fun MyAppNavHost(
    modifier: Modifier = Modifier,
    navController: NavHostController = rememberNavController(),

) {
    NavHost(
        modifier = modifier,
        navController = navController,
        startDestination = Profile
    ) {
        composable<Profile> {
            ProfileScreen(
                onNavigateToFriends = { navController.navigate(route = FriendsList) },
                /*...*/
            )
        }
        composable<FriendsList> { FriendsListScreen(/*...*/) }
    }
}

@Composable
fun ProfileScreen(
    onNavigateToFriends: () -> Unit,
    /*...*/
) {
    /*...*/
    Button(onClick = onNavigateToFriends) {
        Text(text = "See friends list")
    }
}

Menavigasi menggunakan ID bilangan bulat

Untuk menavigasi ke tujuan menggunakan ID bilangan bulat, panggil overload navigate(int). Overload ini mengambil ID resource dari tindakan atau tujuan. Cuplikan kode berikut menunjukkan cara menggunakan overload ini untuk menavigasi ke ViewTransactionsFragment:

Kotlin

viewTransactionsButton.setOnClickListener { view ->
  view.findNavController().navigate(R.id.viewTransactionsAction)
}

Java

viewTransactionsButton.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View view) {
      Navigation.findNavController(view).navigate(R.id.viewTransactionsAction);
  }
});

Saat bernavigasi menggunakan ID, Anda harus menggunakan tindakan jika memungkinkan. Tindakan menyediakan informasi tambahan pada grafik navigasi, menunjukkan secara visual bagaimana tujuan Anda saling terhubung.

Menavigasi menggunakan NavDeepLinkRequest

Untuk menavigasi ke tujuan deep link implisit, gunakan overload navigate(NavDeepLinkRequest). Cuplikan berikut menyediakan implementasi metode ini:

Kotlin

val request = NavDeepLinkRequest.Builder
  .fromUri("android-app://androidx.navigation.app/profile".toUri())
  .build()
findNavController().navigate(request)

Java

NavDeepLinkRequest request = NavDeepLinkRequest.Builder
  .fromUri(Uri.parse("android-app://androidx.navigation.app/profile"))
  .build()
NavHostFragment.findNavController(this).navigate(request)

Tidak seperti navigasi yang menggunakan ID tindakan atau tujuan, Anda dapat menavigasi ke deep link mana pun di grafik Anda, terlepas dari apakah tujuan itu terlihat atau tidak. Anda dapat menavigasi ke tujuan pada grafik saat ini atau tujuan pada grafik yang benar-benar berbeda.

Tindakan dan jenis MIME

Selain Uri, NavDeepLinkRequest juga mendukung deep link dengan tindakan dan jenis MIME. Untuk menambahkan tindakan ke permintaan, gunakan fromAction() atau setAction(). Untuk menambahkan jenis MIME ke permintaan, gunakan fromMimeType() atau setMimeType().

Agar NavDeepLinkRequest dapat mencocokkan tujuan deep link implisit dengan benar, URI, tindakan, dan jenis MIME harus cocok dengan NavDeepLink di tujuan. URI harus cocok dengan pola, tindakan harus sama persis, dan jenis MIME harus berhubungan. Misalnya, image/jpg cocok dengan image/\*

Konteks lebih lanjut

Dokumen ini membahas cara menggunakan NavController.navigate() dalam kasus penggunaan yang paling umum. Namun, fungsi ini memiliki berbagai overload yang dapat Anda gunakan dalam konteks yang berbeda, dan digunakan bersama framework UI manapun. Baca dokumentasi referensi untuk mengetahui detail selengkapnya tentang overload ini.

Bacaan lebih lanjut

Untuk informasi lebih lanjut, lihat halaman berikut: