Membuat tata letak daftar-detail

Daftar-detail adalah pola UI yang terdiri dari tata letak panel ganda, dengan satu panel menampilkan daftar item dan panel lainnya menampilkan detail item yang dipilih dari daftar.

Pola ini sangat berguna untuk aplikasi yang memberikan informasi mendalam tentang elemen koleksi besar, misalnya, program email yang memiliki daftar email dan konten mendetail dari setiap pesan email. Daftar-detail juga dapat digunakan untuk jalur yang kurang penting, seperti membagi preferensi aplikasi menjadi daftar kategori dengan preferensi untuk setiap kategori di panel detail.

Panel detail ditampilkan di samping halaman daftar.
Gambar 1. Jika ukuran layar mencukupi, panel detail akan ditampilkan bersama panel daftar.
Setelah item dipilih, panel detail akan mengambil alih seluruh layar.
Gambar 2. Jika ukuran layar terbatas, panel detail (karena item telah dipilih) akan mengambil alih seluruh ruang.

Mengimplementasikan Pola Daftar-Detail dengan NavigableListDetailPaneScaffold

NavigableListDetailPaneScaffold adalah composable yang menyederhanakan penerapan tata letak daftar-detail di Jetpack Compose. Komponen ini menggabungkan ListDetailPaneScaffold serta menambahkan navigasi bawaan dan animasi kembali prediktif.

Scaffold daftar-detail mendukung hingga tiga panel:

  1. Panel daftar: Menampilkan kumpulan item.
  2. Panel detail: Menampilkan detail item yang dipilih.
  3. Panel tambahan (opsional): Memberikan konteks tambahan jika diperlukan.

Scaffold beradaptasi berdasarkan ukuran jendela:

  • Di jendela besar, panel daftar dan detail akan muncul berdampingan.
  • Di jendela kecil, hanya satu panel yang terlihat dalam satu waktu, yang beralih saat pengguna melakukan navigasi.

Mendeklarasikan dependensi

NavigableListDetailPaneScaffold adalah bagian dari library navigasi adaptif Material 3.

Tambahkan tiga dependensi terkait berikut ke file build.gradle aplikasi atau modul Anda:

Kotlin

implementation("androidx.compose.material3.adaptive:adaptive")
implementation("androidx.compose.material3.adaptive:adaptive-layout")
implementation("androidx.compose.material3.adaptive:adaptive-navigation")

Groovy

implementation 'androidx.compose.material3.adaptive:adaptive'
implementation 'androidx.compose.material3.adaptive:adaptive-layout'
implementation 'androidx.compose.material3.adaptive:adaptive-navigation'
  • adaptif: Elemen penyusun tingkat rendah seperti HingeInfo dan Posture
  • adaptive-layout: Tata letak adaptif seperti ListDetailPaneScaffold dan SupportingPaneScaffold
  • adaptive-navigation: Composable untuk menavigasi di dalam dan di antara panel, serta tata letak adaptif yang mendukung navigasi secara default seperti NavigableListDetailPaneScaffold dan NavigableSupportingPaneScaffold

Pastikan project Anda menyertakan compose-material3-adaptive versi 1.1.0-beta1 atau yang lebih baru.

Memilih untuk menggunakan gestur kembali prediktif

Untuk mengaktifkan animasi kembali prediktif di Android 15 atau yang lebih rendah, Anda harus mengaktifkan dukungan untuk gestur kembali prediktif. Untuk memilih ikut serta, tambahkan android:enableOnBackInvokedCallback="true" ke tag <application> atau tag <activity> individual dalam file AndroidManifest.xml Anda. Untuk mengetahui informasi selengkapnya, lihat Memilih untuk menggunakan gestur kembali prediktif.

Setelah aplikasi Anda menargetkan Android 16 (level API 36) atau yang lebih tinggi, kembali prediktif akan diaktifkan secara default.

Penggunaan dasar

Terapkan NavigableListDetailPaneScaffold sebagai berikut:

  1. Gunakan class yang mewakili konten yang dipilih. Gunakan class Parcelable untuk mendukung penyimpanan dan pemulihan item daftar yang dipilih. Gunakan plugin kotlin-parcelize untuk membuat kode untuk Anda.
  2. Membuat ThreePaneScaffoldNavigator dengan rememberListDetailPaneScaffoldNavigator.

Navigator ini digunakan untuk berpindah antara panel daftar, detail, dan tambahan. Dengan mendeklarasikan jenis generik, navigator juga melacak status scaffold (yaitu, MyItem yang sedang ditampilkan). Karena jenis ini dapat dipaketkan, status dapat disimpan dan dipulihkan oleh navigator untuk otomatis menangani perubahan konfigurasi.

  1. Teruskan navigator ke composable NavigableListDetailPaneScaffold.

  2. Berikan implementasi panel daftar Anda ke NavigableListDetailPaneScaffold. Gunakan AnimatedPane untuk menerapkan animasi panel default selama navigasi. Kemudian, gunakan ThreePaneScaffoldNavigator untuk membuka panel detail, ListDetailPaneScaffoldRole.Detail, dan menampilkan item yang diteruskan.

  3. Sertakan implementasi panel detail Anda di NavigableListDetailPaneScaffold.

Setelah navigasi selesai, currentDestination akan berisi panel yang telah dibuka oleh aplikasi Anda, termasuk konten yang ditampilkan di panel tersebut. Properti contentKey adalah jenis yang sama dengan yang ditentukan dalam panggilan asli sehingga Anda dapat mengakses data apa pun yang perlu ditampilkan.

  1. Jika ingin, ubah defaultBackBehavior di NavigableListDetailPaneScaffold. Secara default, NavigableListDetailPaneScaffold menggunakan PopUntilScaffoldValueChange untuk defaultBackBehavior.

Jika aplikasi Anda memerlukan pola navigasi kembali yang berbeda, Anda dapat mengganti perilaku ini dengan menentukan opsi BackNavigationBehavior lain.

Opsi BackNavigationBehavior

Bagian berikut menggunakan contoh aplikasi email dengan daftar email di satu panel dan tampilan mendetail di panel lainnya.

Perilaku ini berfokus pada perubahan struktur tata letak secara keseluruhan. Dalam penyiapan multi-panel, mengubah konten email di panel detail tidak akan mengubah struktur tata letak yang mendasarinya. Oleh karena itu, tombol kembali mungkin akan keluar dari aplikasi atau grafik navigasi saat ini karena tidak ada perubahan tata letak yang dapat dikembalikan dalam konteks saat ini. Dalam tata letak panel tunggal, menekan kembali akan melewati perubahan konten dalam tampilan detail dan kembali ke tampilan daftar, karena hal ini menunjukkan perubahan tata letak yang jelas.

Perhatikan contoh berikut:

  • Multi-Panel: Anda sedang melihat email (Item 1) di panel detail. Mengklik email lain (Item 2) akan memperbarui panel detail, tetapi panel daftar dan detail tetap terlihat. Menekan kembali mungkin akan keluar dari aplikasi atau alur navigasi saat ini.
  • Panel Tunggal: Anda melihat Item 1, lalu Item 2, menekan kembali akan mengembalikan Anda langsung ke panel daftar email.

Gunakan ini jika Anda ingin pengguna melihat transisi tata letak yang berbeda dengan setiap tindakan kembali.

Ilustrasi yang menunjukkan perubahan nilai navigasi di berbagai panel tata letak.
PopUntilContentChange

Perilaku ini memprioritaskan konten yang ditampilkan. Jika Anda melihat Item 1, lalu Item 2, menekan kembali akan mengembalikan ke Item 1, terlepas dari tata letaknya.

Perhatikan contoh berikut:

  • Multi-Panel: Anda melihat Item 1 di panel detail, lalu mengklik Item 2 dalam daftar. Panel detail akan diperbarui. Menekan kembali akan memulihkan panel detail ke Item 1.
  • Satu Panel: Pengembalian konten yang sama terjadi.

Gunakan ini saat pengguna Anda ingin kembali ke konten yang dilihat sebelumnya dengan tindakan kembali.

transisi antara dua panel detail
PopUntilCurrentDestinationChange

Perilaku ini akan memunculkan data sebelumnya hingga tujuan navigasi saat ini berubah. Hal ini berlaku sama untuk tata letak panel tunggal dan multi-panel.

Perhatikan contoh berikut:

Terlepas dari apakah Anda berada dalam tata letak panel tunggal atau multi-panel, menekan kembali akan selalu memindahkan fokus dari elemen navigasi yang ditandai ke tujuan sebelumnya. Di aplikasi email kita, ini berarti indikasi visual panel yang dipilih akan bergeser.

Gunakan ini jika mempertahankan indikasi visual yang jelas dari navigasi saat ini sangat penting untuk pengalaman pengguna.

menavigasi antara panel detail dan daftar
PopLatest

Opsi ini hanya menghapus tujuan terbaru dari data sebelumnya. Gunakan opsi ini untuk navigasi kembali tanpa melewati status perantara.

Setelah Anda menerapkan langkah-langkah ini, kode Anda akan terlihat seperti berikut:

NavigableListDetailPaneScaffold(
    navigator = navigator,
    listPane = {
        AnimatedPane {
            ListContent(
                words = sampleWords,
                selectionState = navigator.currentDestination?.contentKey?.let {
                    SelectionVisibilityState.ShowSelection(it)
                } ?: SelectionVisibilityState.NoSelection,
                onWordClick = { word ->
                    scope.launch {
                        navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, word)
                    }
                },
                animatedVisibilityScope = this@AnimatedPane,
                sharedTransitionScope = this@SharedTransitionLayout
            )
        }
    },
    detailPane = {
        AnimatedPane {
            DetailContent(
                definedWord = navigator.currentDestination?.contentKey,
                animatedVisibilityScope = this@AnimatedPane,
                sharedTransitionScope = this@SharedTransitionLayout,
                onClosePane = {
                    scope.launch {
                        navigator.navigateBack(
                            backNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange
                        )

                    }
                }
            )
        }
    }