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:
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áveis: elementos básicos de nível inferior, como
HingeInfo
ePosture
- 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() }
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 = { /*...*/ }, )
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") } }, )
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") } }
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() }, )