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, sedangkan panel pendukung menampilkan daftar film lain yang memiliki tema serupa atau sutradara yang sama atau aktor yang dibintangi. Untuk informasi selengkapnya tentang tata letak kanonis panel pendukung, lihat Panduan panel pendukung Material 3.

Mengimplementasikan panel pendukung

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

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
• adaptive-layout — Tata letak adaptif, seperti SupportingPaneScaffold
• Adaptive-navigation — 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 spasi yang akan digunakan, serta ThreePaneScaffoldValue, yang memberikan 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 adalah 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 setiap panel SupportingPaneScaffold ke dalam composablenya sendiri agar dapat digunakan kembali dan 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 hal 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