Memahami dan menerapkan dasar-dasarnya

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Navigasi menjelaskan cara pengguna berpindah-pindah di aplikasi Anda. Pengguna berinteraksi dengan elemen UI, biasanya dengan mengetuk atau mengkliknya, dan aplikasi merespons dengan menampilkan konten baru. Jika ingin kembali ke konten sebelumnya, pengguna akan menggunakan gestur kembali atau mengetuk tombol kembali.

Membuat model status navigasi

Cara yang mudah untuk membuat model perilaku ini adalah dengan tumpukan konten. Saat pengguna menavigasi maju ke konten baru, konten tersebut akan didorong ke atas stack. Saat mereka kembali dari konten tersebut, konten akan dikeluarkan dari stack dan konten sebelumnya akan ditampilkan. Dalam istilah navigasi, stack ini biasanya disebut sebagai data sebelumnya karena mewakili konten yang dapat dibuka kembali oleh pengguna.

Membuat data sebelumnya

Di Navigasi 3, data sebelumnya sebenarnya tidak berisi konten. Sebagai gantinya, file ini berisi referensi ke konten, yang dikenal sebagai kunci. Kunci dapat berupa jenis apa pun, tetapi biasanya berupa class data sederhana yang dapat diserialisasi. Menggunakan referensi, bukan konten, memiliki manfaat berikut:

• Anda dapat dengan mudah menavigasi dengan memasukkan kunci ke data sebelumnya.
• Selama kunci dapat diserialisasi, data sebelumnya dapat disimpan ke penyimpanan persisten, sehingga dapat bertahan saat terjadi perubahan konfigurasi dan proses berhenti. Hal ini penting karena pengguna berharap dapat meninggalkan aplikasi Anda, kembali ke aplikasi tersebut nanti, dan melanjutkan dari bagian yang mereka tinggalkan dengan konten yang sama ditampilkan. Lihat Menyimpan data sebelumnya untuk mengetahui informasi selengkapnya.

Konsep utama dalam Navigation 3 API adalah Anda memiliki data sebelumnya. Library:

• Mengharapkan bahwa data sebelumnya Anda akan menjadi List<T> yang didukung status snapshot, dengan T adalah jenis data sebelumnya keys. Anda dapat menggunakan Any atau memberikan kunci Anda sendiri yang lebih kuat. Saat Anda melihat istilah "push" atau "pop", implementasi yang mendasarinya adalah menambahkan atau menghapus item dari akhir daftar.
• Mengamati data sebelumnya dan mencerminkan statusnya di UI menggunakan NavDisplay.

Contoh berikut menunjukkan cara membuat kunci dan data sebelumnya, serta mengubah data sebelumnya sebagai respons terhadap peristiwa navigasi pengguna:

// Define keys that will identify content
data object ProductList
data class ProductDetail(val id: String)

@Composable
fun MyApp() {

    // Create a back stack, specifying the key the app should start with
    val backStack = remember { mutableStateListOf<Any>(ProductList) }

    // Supply your back stack to a NavDisplay so it can reflect changes in the UI
    // ...more on this below...

    // Push a key onto the back stack (navigate forward), the navigation library will reflect the change in state
    backStack.add(ProductDetail(id = "ABC"))

    // Pop a key off the back stack (navigate back), the navigation library will reflect the change in state
    backStack.removeLastOrNull()
}
BasicSnippets.kt

Me-resolve kunci ke konten

Konten dimodelkan di Navigation 3 menggunakan NavEntry, yang merupakan class yang berisi fungsi composable. Ini mewakili tujuan - satu bagian konten yang dapat dinavigasi pengguna ke depan dan kembali dari.

NavEntry juga dapat berisi metadata - informasi tentang konten. Metadata ini dapat dibaca oleh objek penampung, seperti NavDisplay, untuk membantunya memutuskan cara menampilkan konten NavEntry. Misalnya, metadata dapat digunakan untuk mengganti animasi default untuk NavEntry tertentu. NavEntry metadata adalah peta kunci String ke nilai Any, yang menyediakan penyimpanan data yang serbaguna.

Untuk mengonversi key menjadi NavEntry, buat entryProvider. Ini adalah fungsi yang menerima key dan menampilkan NavEntry untuk key tersebut. Parameter ini biasanya ditentukan sebagai parameter lambda saat membuat NavDisplay.

Ada dua cara untuk membuat entryProvider, yaitu dengan membuat fungsi lambda secara langsung, atau dengan menggunakan DSL entryProvider.

Membuat fungsi entryProvider secara langsung

Anda biasanya membuat fungsi entryProvider menggunakan pernyataan when, dengan cabang untuk setiap kunci.

entryProvider = { key ->
    when (key) {
        is ProductList -> NavEntry(key) { Text("Product List") }
        is ProductDetail -> NavEntry(
            key,
            metadata = mapOf("extraDataKey" to "extraDataValue")
        ) { Text("Product ${key.id} ") }

        else -> {
            NavEntry(Unit) { Text(text = "Invalid Key: $it") }
        }
    }
}
BasicSnippets.kt

Menggunakan DSL entryProvider

DSL entryProvider dapat menyederhanakan fungsi lambda Anda dengan menghindari kebutuhan untuk melakukan pengujian terhadap setiap jenis kunci, dan membuat NavEntry untuk setiap jenis kunci. Gunakan fungsi builder entryProvider untuk melakukannya. Fungsi ini juga menyertakan perilaku penggantian default (menampilkan error) jika kunci tidak ditemukan.

entryProvider = entryProvider {
    entry<ProductList> { Text("Product List") }
    entry<ProductDetail>(
        metadata = mapOf("extraDataKey" to "extraDataValue")
    ) { key -> Text("Product ${key.id} ") }
}
BasicSnippets.kt

Perhatikan hal berikut dari cuplikan:

• entry digunakan untuk menentukan NavEntry dengan jenis dan konten composable tertentu
• entry menerima parameter metadata untuk menetapkan NavEntry.metadata

Menampilkan data sebelumnya

Data sebelumnya mewakili status navigasi aplikasi Anda. Setiap kali data sebelumnya berubah, UI aplikasi harus mencerminkan status data sebelumnya yang baru. Di Navigasi 3, NavDisplay mengamati data sebelumnya dan mengupdate UI-nya sebagaimana mestinya. Buat dengan parameter berikut:

• Data sebelumnya - ini harus berjenis SnapshotStateList<T>, dengan T adalah jenis kunci data sebelumnya. Ini adalah List yang dapat diamati sehingga memicu rekomposisi NavDisplay saat berubah.
• entryProvider untuk mengonversi kunci di data sebelumnya menjadi NavEntry.
• Jika ingin, berikan lambda ke parameter onBack. Ini dipanggil saat pengguna memicu peristiwa kembali.

Contoh berikut menunjukkan cara membuat NavDisplay.

data object Home
data class Product(val id: String)

@Composable
fun NavExample() {

    val backStack = remember { mutableStateListOf<Any>(Home) }

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        entryProvider = { key ->
            when (key) {
                is Home -> NavEntry(key) {
                    ContentGreen("Welcome to Nav3") {
                        Button(onClick = {
                            backStack.add(Product("123"))
                        }) {
                            Text("Click to navigate")
                        }
                    }
                }

                is Product -> NavEntry(key) {
                    ContentBlue("Product ${key.id} ")
                }

                else -> NavEntry(Unit) { Text("Unknown route") }
            }
        }
    )
}
BasicSnippets.kt

Secara default, NavDisplay menampilkan NavEntry teratas di data sebelumnya dalam tata letak panel tunggal. Rekaman berikut menunjukkan aplikasi ini berjalan:

Penutup

Diagram berikut menunjukkan aliran data di antara berbagai objek di Navigation 3:

1. Peristiwa navigasi memulai perubahan. Kunci ditambahkan atau dihapus dari data sebelumnya sebagai respons terhadap interaksi pengguna.

2. Perubahan status data sebelumnya memicu pengambilan konten. NavDisplay (composable yang merender data sebelumnya) mengamati data sebelumnya. Dalam konfigurasi defaultnya, class ini menampilkan entri data sebelumnya teratas dalam satu tata letak panel. Saat kunci teratas di data sebelumnya berubah, NavDisplay menggunakan kunci ini untuk meminta konten yang sesuai dari penyedia entri.

3. Penyedia entri menyediakan konten. Penyedia entri adalah fungsi yang menyelesaikan kunci ke NavEntry. Setelah menerima kunci dari NavDisplay, penyedia entri akan memberikan NavEntry terkait, yang berisi kunci dan konten.

4. Konten ditampilkan. NavDisplay menerima NavEntry dan menampilkan konten.