Criar um layout de painel de suporte

O layout do painel de suporte mantém o foco do usuário no conteúdo principal do app enquanto mostra informações de suporte relevantes. Por exemplo, o painel principal pode mostrar detalhes sobre um filme, enquanto o painel de suporte lista filmes semelhantes, do mesmo diretor ou com os mesmos atores.

Para mais detalhes, consulte as diretrizes do painel de suporte do Material 3.

Implementar um painel de suporte com um scaffold

NavigableSupportingPaneScaffold é um elemento combinável que simplifica a implementação de um layout de painel de suporte no Jetpack Compose. Ele envolve SupportingPaneScaffold e adiciona navegação integrada e processamento de volta preditiva.

Um scaffold de painel de suporte pode ter até três painéis:

  • Painel principal: mostra o conteúdo principal.
  • Painel de suporte: fornece mais contexto ou ferramentas relacionadas ao painel principal.
  • Painel extra (opcional): usado para conteúdo complementar quando necessário.

O scaffold se adapta com base no tamanho da janela:

  • Em janelas grandes, os painéis principal e de suporte aparecem lado a lado.

  • Em janelas pequenas, apenas um painel fica visível por vez, alternando conforme os usuários navegam.

    Conteúdo principal ocupando a maior parte da tela com conteúdo de suporte ao lado.
    Figura 1. Layout do painel de suporte.

Adicionar dependências

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

Adicione as três dependências relacionadas a seguir 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.

  • adaptive-layout: layouts adaptáveis, como ListDetailPaneScaffold e SupportingPaneScaffold.

  • adaptive-navigation: elementos que podem ser compostos para navegar dentro e entre painéis, além de layouts adaptáveis que oferecem suporte à navegação por padrão, como NavigableListDetailPaneScaffold e NavigableSupportingPaneScaffold.

Verifique se o projeto inclui a versão 1.1.0-beta1 do compose-material3-adaptive ou mais recente.

Ativar o gesto de volta preditivo

Para ativar as animações de volta preditiva no Android 15 ou versões anteriores, é necessário ativar o suporte ao gesto de volta preditivo. Para ativar, adicione android:enableOnBackInvokedCallback="true" à tag <application> ou a tags <activity> individuais no arquivo AndroidManifest.xml.

Quando o app segmentar o Android 16 (nível 36 da API) ou uma versão mais recente, o gesto de voltar preditivo será ativado por padrão.

Criar um navegador

Em janelas pequenas, apenas um painel é mostrado por vez. Portanto, use um ThreePaneScaffoldNavigator para alternar entre os painéis. Crie uma instância do navegador com rememberSupportingPaneScaffoldNavigator.

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

Transmitir o navegador para o scaffold

O scaffold requer um ThreePaneScaffoldNavigator, que é uma interface que representa o estado do scaffold, o ThreePaneScaffoldValue e um PaneScaffoldDirective.

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = { /*...*/ },
    supportingPane = { /*...*/ },
)

O painel principal e o de suporte são elementos que contêm seu conteúdo. Use AnimatedPane para aplicar as animações de painel padrão durante a 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(SupportingPaneScaffoldRole.Supporting) para exibir o painel de suporte.

Para telas grandes, use o método ThreePaneScaffoldNavigator.navigateBack() para dispensar o painel de suporte, transmitindo a constante BackNavigationBehavior.PopUntilScaffoldValueChange. Chamar esse método força uma recomposição do NavigableSupportingPaneScaffold. Durante a recomposição, verifique a propriedade ThreePaneScaffoldNavigator.currentDestination para determinar se o painel de suporte precisa ser mostrado.

Confira uma implementação completa do scaffold:

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()
val backNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = {
        AnimatedPane(
            modifier = Modifier
                .safeContentPadding()
                .background(Color.Red)
        ) {
            if (scaffoldNavigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Hidden) {
                Button(
                    modifier = Modifier
                        .wrapContentSize(),
                    onClick = {
                        scope.launch {
                            scaffoldNavigator.navigateTo(SupportingPaneScaffoldRole.Supporting)
                        }
                    }
                ) {
                    Text("Show supporting pane")
                }
            } else {
                Text("Supporting pane is shown")
            }
        }
    },
    supportingPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            Column {
                // Allow users to dismiss the supporting pane. Use back navigation to
                // hide an expanded supporting pane.
                if (scaffoldNavigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Expanded) {
                    // Material design principles promote the usage of a right-aligned
                    // close (X) button.
                    IconButton(
                        modifier =  Modifier.align(Alignment.End).padding(16.dp),
                        onClick = {
                            scope.launch {
                                scaffoldNavigator.navigateBack(backNavigationBehavior)
                            }
                        }
                    ) {
                        Icon(Icons.Default.Close, contentDescription = "Close")
                    }
                }
                Text("Supporting pane")
            }

        }
    }
)

Extrair elementos combináveis de painel

Extraia os painéis individuais de um SupportingPaneScaffold para os próprios elementos combináveis para que eles sejam reutilizáveis e testáveis. Use ThreePaneScaffoldScope para acessar AnimatedPane se quiser as animações padrão:

@OptIn(ExperimentalMaterial3AdaptiveApi::class)
@Composable
fun ThreePaneScaffoldPaneScope.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")
        }
    }
}

@OptIn(ExperimentalMaterial3AdaptiveApi::class)
@Composable
fun ThreePaneScaffoldPaneScope.SupportingPane(
    scaffoldNavigator: ThreePaneScaffoldNavigator<Any>,
    modifier: Modifier = Modifier,
    backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange,
) {
    val scope = rememberCoroutineScope()
    AnimatedPane(modifier = Modifier.safeContentPadding()) {
        Column {
            // Allow users to dismiss the supporting pane. Use back navigation to
            // hide an expanded supporting pane.
            if (scaffoldNavigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Expanded) {
                // Material design principles promote the usage of a right-aligned
                // close (X) button.
                IconButton(
                    modifier =  modifier.align(Alignment.End).padding(16.dp),
                    onClick = {
                        scope.launch {
                            scaffoldNavigator.navigateBack(backNavigationBehavior)
                        }
                    }
                ) {
                    Icon(Icons.Default.Close, contentDescription = "Close")
                }
            }
            Text("Supporting pane")
        }

    }
}

Extrair os painéis em elementos de composição simplifica o uso do SupportingPaneScaffold (compare o seguinte com a implementação completa do scaffold na seção anterior):

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = {
        MainPane(
            shouldShowSupportingPaneButton = scaffoldNavigator.scaffoldValue.secondary == PaneAdaptedValue.Hidden,
            onNavigateToSupportingPane = {
                scope.launch {
                    scaffoldNavigator.navigateTo(ThreePaneScaffoldRole.Secondary)
                }
            }
        )
    },
    supportingPane = { SupportingPane(scaffoldNavigator = scaffoldNavigator) },
)

Se você precisar de mais controle sobre aspectos específicos do scaffold, use SupportingPaneScaffold em vez de NavigableSupportingPaneScaffold. Ele aceita um PaneScaffoldDirective e ThreePaneScaffoldValue ou ThreePaneScaffoldState separadamente. Essa flexibilidade permite implementar uma lógica personalizada para o espaçamento de painéis e determinar quantos painéis precisam ser mostrados simultaneamente. Também é possível ativar o suporte para volta preditiva adicionando ThreePaneScaffoldPredictiveBackHandler.

Adicionar ThreePaneScaffoldPredictiveBackHandler

Anexe o gerenciador de volta preditivo que usa uma instância de navegador de scaffold e especifique o backBehavior. Isso determina como os destinos são retirados da backstack durante a navegação de retorno. Em seguida, transmita scaffoldDirective e scaffoldState para SupportingPaneScaffold. Use a sobrecarga que aceita um ThreePaneScaffoldState, transmitindo scaffoldNavigator.scaffoldState.

Defina os painéis principal e de suporte em SupportingPaneScaffold. Use AnimatedPane para animações de painel padrão.

Depois de implementar essas etapas, o código vai ficar parecido com este:

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

ThreePaneScaffoldPredictiveBackHandler(
    navigator = scaffoldNavigator,
    backBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange
)

SupportingPaneScaffold(
    directive = scaffoldNavigator.scaffoldDirective,
    scaffoldState = scaffoldNavigator.scaffoldState,
    mainPane = {
        MainPane(
            shouldShowSupportingPaneButton = scaffoldNavigator.scaffoldValue.secondary == PaneAdaptedValue.Hidden,
            onNavigateToSupportingPane = {
                scope.launch {
                    scaffoldNavigator.navigateTo(ThreePaneScaffoldRole.Secondary)
                }
            }
        )
    },
    supportingPane = { SupportingPane(scaffoldNavigator = scaffoldNavigator) },
)