Criar um layout de painel de suporte

O layout canônico do painel de suporte concentra a atenção do usuário no conteúdo principal do app e exibe conteúdo de suporte relevante. Por exemplo, o painel principal de conteúdo pode mostrar informações sobre um filme recente, enquanto o painel de suporte exibe uma lista de outros filmes com temas semelhantes ou com o mesmo diretor ou atores principais. Para mais informações sobre o layout canônico do painel de suporte, consulte as diretrizes do painel de suporte do Material 3.

Implementar um painel de suporte

O SupportingPaneScaffold consiste em até três painéis: um principal, um de suporte e um extra opcional. O esqueleto processa todos os cálculos para alocar espaço da janela aos três painéis. Em telas grandes, o esqueleto mostra o painel principal com o painel de suporte ao lado. Em telas pequenas, o esqueleto mostra o painel principal ou de suporte em tela cheia.

Figura 1. Layout do painel de suporte.

Adicionar dependências

SupportingPaneScaffold faz parte da biblioteca de layout adaptável do Material 3.

Adicione as três dependências relacionadas abaixo ao arquivo build.gradle do seu app ou módulo:

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'

• adaptável: elementos básicos de baixo nível, como HingeInfo e Posture
• layout-adaptável: os layouts adaptáveis, como SupportingPaneScaffold.
• adaptive-navigation: elementos combináveis para navegar dentro e entre os painéis.

Criar um navegador e um esqueleto

Em janelas pequenas, apenas um painel é exibido por vez. Use um ThreePaneScaffoldNavigator para alternar entre painéis. Crie uma instância do navegador com rememberSupportingPaneScaffoldNavigator. Para processar gestos de volta, use um BackHandler que verifique canNavigateBack() e chame navigateBack():

val navigator = rememberSupportingPaneScaffoldNavigator()

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

O esqueleto exige um PaneScaffoldDirective, que controla como dividir a tela e quanto espaço usar, e um ThreePaneScaffoldValue, que fornece o estado atual dos painéis (por exemplo, se eles estão abertos ou ocultos). Para o comportamento padrão, use scaffoldDirective e scaffoldValue do navegador, respectivamente:

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

O painel principal e o de suporte são elementos combináveis que contêm seu conteúdo. Use AnimatedPane para aplicar as animações padrão do painel durante a navegação. Use o valor de scaffold para conferir se o painel de suporte está oculto. Nesse caso, mostre um botão que chame navigateTo(ThreePaneScaffoldRole.Secondary) para mostrar o painel de suporte.

Confira uma implementação completa do esqueleto:

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

Extrair elementos combináveis do painel

Extraia os painéis individuais de um SupportingPaneScaffold para os próprios combináveis para torná-los reutilizáveis e testáveis. Use ThreePaneScaffoldScope para acessar AnimatedPane se você quiser as animações padrão:

@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

Extrair as panes em elementos combináveis simplifica o uso do SupportingPaneScaffold (compare o exemplo a seguir com a implementação completa do scaffold na seção anterior):

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