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.

Navigasi

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 membuka composable, Anda harus menggunakan NavController.navigate<T>. Dengan overload ini, navigate() akan menggunakan satu argumen route yang jenisnya Anda teruskan. Argumen ini berfungsi sebagai kunci ke tujuan.

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

Untuk menavigasi ke composable di grafik navigasi, pertama-tama tentukan NavGraph sehingga setiap tujuan sesuai dengan jenis. Untuk composable, Anda dapat 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 mengetahui contohnya.

Peringatan: Jangan teruskan NavController ke composable Anda. Ekspos peristiwa seperti yang dijelaskan di sini.

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 menjelaskan data yang diperlukan oleh tujuan tersebut.
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, kode 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")
    }
}

Peringatan: Anda hanya boleh memanggil navigate() sebagai bagian dari callback, bukan bagian dari composable itu sendiri. Tindakan ini akan menghindari pemanggilan navigate() di setiap rekomposisi.

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.

Catatan: Untuk tombol, terdapat tiga varian Navigation.createNavigateOnClickListener(). Varian ini berguna jika Anda menggunakan bahasa pemrograman Java. Jika Anda menggunakan Kotlin, OnClickListener adalah antarmuka SAM sehingga Anda dapat menggunakan lambda akhir. Pendekatan ini dapat lebih singkat dan lebih mudah dibaca daripada memanggil createNavigateOnClickListener() secara langsung.

Catatan: Untuk menangani komponen UI umum lainnya, seperti panel aplikasi atas dan navigasi bawah, lihat Memperbarui komponen UI dengan NavigationUI.

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.

Perhatian: Saat menavigasi menggunakan NavDeepLinkRequest, data sebelumnya tidak direset. Perilaku ini tidak seperti bentuk lain dari navigasi deep link. Namun, popUpTo() dan popUpToInclusive() tetap menghapus tujuan dari data sebelumnya seolah-olah Anda telah melakukan navigasi menggunakan ID.

Catatan: Untuk memudahkan, Anda juga dapat menggunakan navigate(Uri), yang menggabungkan Uri dalam DeepLinkRequest.

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:

• Membuat pengontrol navigasi
• Navigasi dan data sebelumnya
• Menavigasi dengan opsi
• Keamanan jenis di DSL Kotlin dan Navigation Compose