Criar um layout de painel de suporte

O layout canônico do painel de suporte concentra a atenção do usuário no principal conteúdo e, ao mesmo tempo, mostrar conteúdo de apoio relevante. Por exemplo, o principal o painel de conteúdo pode mostrar informações sobre um filme recente, enquanto o conteúdo exibe uma lista de outros filmes que têm um tema semelhante ou o mesmo diretor ou atores principais. Para mais informações sobre o painel de suporte, no layout canônico, consulte a Diretrizes do painel de suporte do Material 3.

Implementar um painel de suporte

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

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 a seguir ao arquivo build.gradle da sua 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'

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

Criar um navegador e um scaffold

Em janelas pequenas, apenas um painel é exibido por vez, portanto, use uma ThreePaneScaffoldNavigator de ida e volta painéis. Crie uma instância do navegador com rememberSupportingPaneScaffoldNavigator Para processar os gestos "Voltar", use um BackHandler que verifique canNavigateBack() e chamadas navigateBack():

val navigator = rememberSupportingPaneScaffoldNavigator()

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

O scaffold precisa de um PaneScaffoldDirective, que controla como dividir a tela e quanto espaçamento usar, e um ThreePaneScaffoldValue, que fornece o o estado dos painéis (por exemplo, se estão expandidos 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

Os painéis principal e de suporte são elementos combináveis que incluem o conteúdo. Usar AnimatedPane para aplicar as animações de painel padrão durante navegação. Use o valor do scaffold para verificar se o painel de suporte está oculto. Se estiver, mostre um botão que chame navigateTo(ThreePaneScaffoldRole.Secondary) para mostrar o painel de suporte.

Confira uma implementação completa do 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

Extrair elementos combináveis do painel

Extrair os painéis individuais de um SupportingPaneScaffold nos próprios combináveis para torná-los reutilizáveis e testáveis. Usar ThreePaneScaffoldScope para acessar AnimatedPane se você quer 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 os painéis em elementos combináveis simplifica o uso do SupportingPaneScaffold (compare o seguinte com a implementação completa) da estrutura 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