Criar um layout de detalhes e listas

Detalhes de lista é um padrão de interface que consiste em um layout de painel duplo em que um painel apresenta uma lista de itens e outro mostra os detalhes dos itens selecionados na lista.

O padrão é particularmente útil para aplicativos que fornecem informações detalhadas sobre elementos de grandes coleções, por exemplo, um cliente de e-mail que tem uma lista de e-mails e o conteúdo detalhado de cada mensagem. O detalhe da lista também pode ser usado para caminhos menos críticos, como dividir as preferências do app em uma lista de categorias com as preferências de cada categoria no painel de detalhes.

Implementar o padrão da interface com ListDetailPaneScaffold

ListDetailPaneScaffold é um elemento combinável que simplifica a implementação do padrão de detalhes e listas no app. Um scaffolding de detalhes e listas pode consistir em até três painéis: um de lista, um de detalhes e um painel extra opcional. O scaffold processa os cálculos do espaço da tela. Quando o tamanho da tela é suficiente, o painel de detalhes é mostrado ao lado do painel de lista. Em tamanhos de tela pequenos, o esqueleto muda automaticamente para exibir a lista ou o painel de detalhes em tela cheia.

Figura 1. Quando o tamanho da tela está disponível, o painel de detalhes é mostrado ao lado do painel de lista.

Figura 2. Quando o tamanho da tela é limitado, o painel de detalhes (já que um item foi selecionado) ocupa todo o espaço.

Declarar dependências

ListDetailPaneScaffold 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'

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

Uso básico

Implemente ListDetailPaneScaffold desta forma:

1. Use uma classe que represente o conteúdo a ser selecionado. Essa classe precisa ser Parcelable para oferecer suporte ao salvamento e à restauração do item de lista selecionado. Use o plug-in kotlin-parcelize para gerar o código.

   @Parcelize
   class MyItem(val id: Int) : Parcelable
   SampleListDetailPaneScaffold.kt

2. Crie um ThreePaneScaffoldNavigator com rememberListDetailPaneScaffoldNavigator e adicione um BackHandler. Esse navegador é usado para alternar entre a lista, os detalhes e os painéis extras. Ao declarar um tipo genérico, o navegador também rastreia o estado do scaffold, ou seja, qual MyItem está sendo exibido. Como esse tipo é compartilhável, o estado pode ser salvo e restaurado pelo navegador para processar automaticamente as mudanças de configuração. O BackHandler oferece suporte à navegação de volta usando o gesto ou o botão de voltar do sistema. O comportamento esperado do botão "Voltar" para um ListDetailPaneScaffold depende do tamanho da janela e do valor atual do scaffold. Se o ListDetailPaneScaffold puder voltar ao estado atual, o canNavigateBack() será true, ativando o BackHandler.

   val navigator = rememberListDetailPaneScaffoldNavigator<MyItem>()
   
   BackHandler(navigator.canNavigateBack()) {
       navigator.navigateBack()
   }
   SampleListDetailPaneScaffold.kt

3. Transmita o scaffoldState do navigator para o elemento combinável ListDetailPaneScaffold.

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       // ...
   )
   SampleListDetailPaneScaffold.kt

4. Forneça a implementação do painel de lista para o ListDetailPaneScaffold. Use AnimatedPane para aplicar as animações padrão do painel durante a navegação. Em seguida, use ThreePaneScaffoldNavigator para navegar até o painel de detalhes, ListDetailPaneScaffoldRole.Detail, e mostrar o item transmitido.

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       listPane = {
           AnimatedPane {
               MyList(
                   onItemClick = { item ->
                       // Navigate to the detail pane with the passed item
                       navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, item)
                   }
               )
           }
       },
       // ...
   )
   SampleListDetailPaneScaffold.kt

5. Inclua a implementação do painel de detalhes em ListDetailPaneScaffold. Quando a navegação for concluída, currentDestination conterá o painel pelo qual seu app navegou, incluindo o conteúdo exibido no painel. A propriedade content é do mesmo tipo especificado na chamada de recordação original (MyItem neste exemplo). Assim, você também pode acessar a propriedade para qualquer dado que precise mostrar.

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       listPane =
       // ...
       detailPane = {
           AnimatedPane {
               navigator.currentDestination?.content?.let {
                   MyDetails(it)
               }
           }
       },
   )
   SampleListDetailPaneScaffold.kt

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

val navigator = rememberListDetailPaneScaffoldNavigator<MyItem>()

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

ListDetailPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    listPane = {
        AnimatedPane {
            MyList(
                onItemClick = { item ->
                    // Navigate to the detail pane with the passed item
                    navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, item)
                },
            )
        }
    },
    detailPane = {
        AnimatedPane {
            // Show the detail pane content if selected item is available
            navigator.currentDestination?.content?.let {
                MyDetails(it)
            }
        }
    },
)
SampleListDetailPaneScaffold.kt