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 também mostra conteúdo de suporte relevante. Por exemplo, o painel de conteúdo principal pode mostrar informações sobre um filme recente, enquanto o de suporte exibe uma lista de outros filmes que têm um tema semelhante, o mesmo diretor ou atores. Para saber mais sobre o layout canônico do painel de suporte, consulte as Diretrizes do painel de suporte do Material 3 (link em inglês).

Implementar um painel de suporte

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

Adicionar dependências

O 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 app ou módulo:

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'

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

Criar um navegador e um scaffold

Em janelas pequenas, apenas um painel é exibido por vez. Portanto, use um ThreePaneScaffoldNavigator para mover de e para os painéis. Crie uma instância do Navigator com rememberSupportingPaneScaffoldNavigator. Para processar gestos de retorno, use um BackHandler que verifique canNavigateBack() e chame navigateBack():

val navigator = rememberSupportingPaneScaffoldNavigator()

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

O scaffold exige uma PaneScaffoldDirective, que controla como dividir a tela e a quantidade de espaçamento a ser usada, e uma ThreePaneScaffoldValue, que fornece o estado atual dos painéis (por exemplo, se estão expandidos ou ocultos). Para o comportamento padrão, use o scaffoldDirective e o 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 do painel padrão 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 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 os elementos combináveis do painel

Extraia os painéis individuais de uma SupportingPaneScaffold para os próprios elementos combináveis para torná-los reutilizáveis e testáveis. Use ThreePaneScaffoldScope para acessar AnimatedPane se 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

A extração dos painéis para os elementos combináveis simplifica o uso do SupportingPaneScaffold. Compare o seguinte 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