Membangun tata letak panel pendukung

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

Tata letak panel pendukung menjaga fokus pengguna pada konten utama aplikasi sekaligus menampilkan informasi pendukung yang relevan. Misalnya, panel utama mungkin menampilkan detail tentang film, sedangkan panel pendukung mencantumkan film yang serupa, film oleh sutradara yang sama, atau karya yang menampilkan aktor yang sama.

Untuk mengetahui detail selengkapnya, lihat Panduan panel pendukung Material 3.

Mengimplementasikan panel pendukung dengan NavigableSupportingPaneScaffold

NavigableSupportingPaneScaffold adalah composable yang menyederhanakan penerapan tata letak panel pendukung di Jetpack Compose. Fungsi ini menggabungkan SupportingPaneScaffold dan menambahkan navigasi bawaan dan penanganan kembali prediktif.

Scaffold panel pendukung mendukung hingga tiga panel:

• Panel utama: Menampilkan konten utama.
• Panel pendukung: Memberikan konteks atau alat tambahan yang terkait dengan panel utama.
• Panel tambahan (opsional): Digunakan untuk konten tambahan jika diperlukan.

Scaffold beradaptasi berdasarkan ukuran jendela:

• Di jendela besar, panel utama dan pendukung akan muncul berdampingan.

• Di jendela kecil, hanya satu panel yang terlihat dalam satu waktu, yang beralih saat pengguna membuka.

  

Menambahkan dependensi

NavigableSupportingPaneScaffold adalah bagian dari library tata letak adaptif Material 3.

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

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

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 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 tinggi.

Memilih untuk menggunakan gestur kembali prediktif

Untuk mengaktifkan animasi kembali prediktif di Android 15 atau yang lebih rendah, Anda harus memilih untuk mendukung gestur kembali prediktif. Untuk memilih ikut serta, tambahkan android:enableOnBackInvokedCallback="true" ke <application> [tag atau android:enableOnBackInvokedCallback="true" ke <application> tag atau masing-masing <activity> tag dalam file AndroidManifest.xml Anda.

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

Membuat navigator

Di jendela kecil, hanya satu panel yang ditampilkan dalam satu waktu, jadi gunakan ThreePaneScaffoldNavigator untuk berpindah ke dan dari panel. Buat instance navigator dengan rememberSupportingPaneScaffoldNavigator.

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()
SampleSupportingPaneScaffold.kt

Meneruskan navigator ke scaffold

Scaffold memerlukan ThreePaneScaffoldNavigator yang merupakan antarmuka yang mewakili status scaffold, ThreePaneScaffoldValue, dan PaneScaffoldDirective.

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = { /*...*/ },
    supportingPane = { /*...*/ },
)
SampleSupportingPaneScaffold.kt

Panel utama dan panel pendukung adalah composable yang berisi konten Anda. Gunakan AnimatedPane untuk menerapkan animasi panel default selama navigasi. Gunakan nilai scaffold untuk memeriksa apakah panel pendukung tersembunyi; jika ya, tampilkan tombol yang memanggil navigateTo(SupportingPaneScaffoldRole.Supporting) untuk menampilkan panel pendukung.

Berikut adalah implementasi lengkap scaffold:

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = {
        AnimatedPane(
            modifier = Modifier
                .safeContentPadding()
                .background(Color.Red)
        ) {
            if (scaffoldNavigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Hidden) {
                Button(
                    modifier = Modifier
                        .wrapContentSize(),
                    onClick = {
                        scope.launch {
                            scaffoldNavigator.navigateTo(SupportingPaneScaffoldRole.Supporting)
                        }
                    }
                ) {
                    Text("Show supporting pane")
                }
            } else {
                Text("Supporting pane is shown")
            }
        }
    },
    supportingPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            Text("Supporting pane")
        }
    }
)
SampleSupportingPaneScaffold.kt

Mengekstrak composable panel

Ekstrak setiap panel SupportingPaneScaffold ke dalam composablenya sendiri agar dapat digunakan kembali dan diuji. Gunakan ThreePaneScaffoldScope untuk mengakses AnimatedPane jika Anda menginginkan animasi default:

@OptIn(ExperimentalMaterial3AdaptiveApi::class)
@Composable
fun ThreePaneScaffoldPaneScope.MainPane(
    shouldShowSupportingPaneButton: Boolean,
    onNavigateToSupportingPane: () -> Unit,
    modifier: Modifier = Modifier,
) {
    AnimatedPane(
        modifier = modifier.safeContentPadding()
    ) {
        // Main pane content
        if (shouldShowSupportingPaneButton) {
            Button(onClick = onNavigateToSupportingPane) {
                Text("Show supporting pane")
            }
        } else {
            Text("Supporting pane is shown")
        }
    }
}

@OptIn(ExperimentalMaterial3AdaptiveApi::class)
@Composable
fun ThreePaneScaffoldPaneScope.SupportingPane(
    modifier: Modifier = Modifier,
) {
    AnimatedPane(modifier = modifier.safeContentPadding()) {
        // Supporting pane content
        Text("This is the supporting pane")
    }
}
SampleSupportingPaneScaffold.kt

Mengekstrak panel menjadi composable akan menyederhanakan penggunaan SupportingPaneScaffold (bandingkan hal berikut dengan implementasi lengkap scaffold di bagian sebelumnya):

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = {
        MainPane(
            shouldShowSupportingPaneButton = scaffoldNavigator.scaffoldValue.secondary == PaneAdaptedValue.Hidden,
            onNavigateToSupportingPane = {
                scope.launch {
                    scaffoldNavigator.navigateTo(ThreePaneScaffoldRole.Secondary)
                }
            }
        )
    },
    supportingPane = { SupportingPane() },
)
SampleSupportingPaneScaffold.kt

Jika Anda memerlukan kontrol lebih besar atas aspek tertentu dari scaffold, sebaiknya gunakan SupportingPaneScaffold, bukan NavigableSupportingPaneScaffold. Tindakan ini menerima PaneScaffoldDirective dan ThreePaneScaffoldValue atau ThreePaneScaffoldState secara terpisah. Fleksibilitas ini memungkinkan Anda menerapkan logika kustom untuk spasi panel dan menentukan jumlah panel yang harus ditampilkan secara bersamaan. Anda juga dapat mengaktifkan dukungan kembali prediktif dengan menambahkan ThreePaneScaffoldPredictiveBackHandler.

Menambahkan ThreePaneScaffoldPredictiveBackHandler

Lampirkan pengendali kembali prediktif yang menggunakan instance navigator scaffold dan tentukan backBehavior. Ini menentukan cara tujuan ditampilkan dari data sebelumnya selama navigasi kembali. Kemudian, teruskan scaffoldDirective dan scaffoldState ke SupportingPaneScaffold. Gunakan overload yang menerima ThreePaneScaffoldState, yang meneruskan scaffoldNavigator.scaffoldState.

Tentukan panel utama dan pendukung dalam SupportingPaneScaffold. Gunakan AnimatedPane untuk animasi panel default.

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

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

ThreePaneScaffoldPredictiveBackHandler(
    navigator = scaffoldNavigator,
    backBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange
)

SupportingPaneScaffold(
    directive = scaffoldNavigator.scaffoldDirective,
    scaffoldState = scaffoldNavigator.scaffoldState,
    mainPane = {
        MainPane(
            shouldShowSupportingPaneButton = scaffoldNavigator.scaffoldValue.secondary == PaneAdaptedValue.Hidden,
            onNavigateToSupportingPane = {
                scope.launch {
                    scaffoldNavigator.navigateTo(ThreePaneScaffoldRole.Secondary)
                }
            }
        )
    },
    supportingPane = { SupportingPane() },
)
SampleSupportingPaneScaffold.kt