Crea un layout per i riquadri di supporto

Il layout canonico del riquadro di supporto concentra l'attenzione degli utenti sugli elementi principali della tua app contenuti pertinenti, mostrando al contempo contenuti di supporto pertinenti. Ad esempio, l'elemento principale potrebbe mostrare informazioni su un film recente mentre il riquadro dei contenuti visualizza un elenco di altri film che hanno un tema simile o uguale registi o protagonisti attori. Per ulteriori informazioni sul riquadro di supporto layout canonico, consulta Linee guida per il riquadro di supporto del materiale 3.

Implementare un riquadro di supporto

SupportingPaneScaffold è composto da un massimo di tre riquadri: un riquadro principale, un riquadro di supporto e un riquadro aggiuntivo facoltativo. La struttura preliminare gestisce tutti i calcoli per l'allocazione dello spazio della finestra ai tre riquadri. Attivato schermi di grandi dimensioni, sullo scaffold è visualizzato il riquadro principale con il riquadro di supporto di lato. Su schermi di piccole dimensioni, lo scaffold mostra la parte principale o quella di supporto riquadro a schermo intero.

Contenuti principali che occupano la maggior parte dell'area del display, affiancati da contenuti di supporto.
Figura 1. Layout del riquadro di supporto.

Aggiungi dipendenze

SupportingPaneScaffold fa parte di Libreria di layout adattivi di Material 3.

Aggiungi le tre dipendenze correlate seguenti al file build.gradle della tua app o del tuo modulo:

Kotlin

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

Alla moda

implementation 'androidx.compose.material3.adaptive:adaptive'
implementation 'androidx.compose.material3.adaptive:adaptive-layout'
implementation 'androidx.compose.material3.adaptive:adaptive-navigation'
  • Adattiva: componenti di base di basso livello come HingeInfo e Posture
  • adaptive-layout: i layout adattivi, come SupportingPaneScaffold
  • navigazione adattiva: elementi componibili per la navigazione all'interno di tra i riquadri

Crea un navigatore e uno scaffold

Nelle finestre piccole viene visualizzato un solo riquadro alla volta, quindi usa una ThreePaneScaffoldNavigator per spostarsi da e verso riquadri. Crea un'istanza del navigatore con rememberSupportingPaneScaffoldNavigator Per gestire i gesti Indietro, usa l'icona BackHandler che controlla canNavigateBack() e chiamate navigateBack():

val navigator = rememberSupportingPaneScaffoldNavigator()

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

Lo scaffold richiede una classe PaneScaffoldDirective, che controlla come dividere lo schermo, la distanza da utilizzare e un ThreePaneScaffoldValue, che fornisce lo stato attuale lo stato dei riquadri (ad esempio, se sono espansi o nascosti). Per impostazione predefinita comportamento, usa i tasti di navigazione scaffoldDirective e scaffoldValue rispettivamente:

SupportingPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    mainPane = { /*...*/ },
    supportingPane = { /*...*/ },
)

Il riquadro principale e il riquadro di supporto sono componibili che contengono i tuoi contenuti. Utilizza le funzionalità di AnimatedPane per applicare le animazioni predefinite dei riquadri durante per la navigazione. Utilizza il valore dello scaffold per verificare se il riquadro di supporto è nascosto; In questo caso, mostra un pulsante che richiama navigateTo(ThreePaneScaffoldRole.Secondary) per visualizzare riquadro di supporto.

Ecco un'implementazione completa dello 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")
        }
    },
)

Estrai riquadri componibili

Estrai i singoli riquadri di un SupportingPaneScaffold nei rispettivi composabili per renderli riutilizzabili e verificabili. Utilizza le funzionalità di ThreePaneScaffoldScope per accedere a AnimatedPane se vuoi le animazioni predefinite:

@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")
    }
}

L'estrazione dei riquadri in componenti composibili semplifica l'utilizzo di SupportingPaneScaffold (confronta quanto segue con l'implementazione completa dello scafo nella sezione precedente):

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() },
)