Membangun tata letak panel pendukung

Tata letak kanonis panel pendukung memfokuskan perhatian pengguna pada konten utama aplikasi Anda sekaligus menampilkan konten pendukung yang relevan. Misalnya, panel konten utama mungkin menampilkan informasi tentang film terbaru, sementara panel pendukung menampilkan daftar film lain yang memiliki tema serupa, sutradara yang sama, atau aktor utama. Untuk informasi selengkapnya tentang tata letak kanonis panel pendukung, lihat Panduan panel pendukung Material 3.

Mengimplementasikan panel pendukung

SupportingPaneScaffold terdiri dari hingga tiga panel: panel utama, panel pendukung, dan panel tambahan opsional. Scaffold menangani semua penghitungan untuk mengalokasikan ruang jendela ke tiga panel. Pada layar besar, scaffold akan menampilkan panel utama dengan panel pendukung di sampingnya. Pada layar kecil, scaffold akan menampilkan layar penuh panel utama atau pendukung.

Menambahkan dependensi

SupportingPaneScaffold 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
• tata letak adaptif — Tata letak adaptif, seperti SupportingPaneScaffold
• navigasi-adaptif — Composable untuk menavigasi di dalam dan antar-panel

Membuat navigator dan scaffold

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. Untuk menangani gestur kembali, gunakan BackHandler yang memeriksa canNavigateBack() dan memanggil navigateBack():

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}
SampleSupportingPaneScaffold.kt

Scaffold memerlukan PaneScaffoldDirective yang mengontrol cara membagi layar dan jumlah ruang yang digunakan, serta ThreePaneScaffoldValue, yang menyediakan status panel saat ini (seperti apakah panel diperluas atau disembunyikan). Untuk perilaku default, gunakan scaffoldDirective dan scaffoldValue navigator:

SupportingPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    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(ThreePaneScaffoldRole.Secondary) untuk menampilkan panel pendukung.

Berikut implementasi lengkap scaffold:

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}

SupportingPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    mainPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            // Main pane content
            if (navigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Hidden) {
                Button(
                    modifier = Modifier.wrapContentSize(),
                    onClick = {
                        navigator.navigateTo(SupportingPaneScaffoldRole.Supporting)
                    }
                ) {
                    Text("Show supporting pane")
                }
            } else {
                Text("Supporting pane is shown")
            }
        }
    },
    supportingPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            // Supporting pane content
            Text("Supporting pane")
        }
    },
)
SampleSupportingPaneScaffold.kt

Mengekstrak composable panel

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

@Composable
fun ThreePaneScaffoldScope.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")
        }
    }
}

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

Mengekstrak panel ke dalam composable akan menyederhanakan penggunaan SupportingPaneScaffold (bandingkan data berikut dengan implementasi lengkap scaffold di bagian sebelumnya):

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}

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