Barras de apps

As barras de apps são contêineres que dão ao usuário acesso aos principais recursos e itens de navegação. Há dois tipos de barras de apps: as superiores e as inferiores. A aparência e a finalidade de cada um são as seguintes:

Tipo

Aparência

Finalidade

Barra de apps superior

Na parte de cima da tela.

Dá acesso a tarefas e informações importantes. Geralmente, ela contém um título, ações necessárias principais e alguns itens de navegação.

Barra de apps inferior

Na parte de baixo da tela.

Normalmente inclui itens de navegação principais. Também pode fornecer acesso a outras ações importantes, como por um botão de ação flutuante contido.

Exemplo de uma barra de apps superior e inferior.
Figura 1. Uma barra de apps superior (à esquerda) e uma barra de apps inferior (à direita).

Para implementar uma barra de apps na parte de cima e outra na parte de baixo, use os elementos combináveis TopAppBar e BottomAppBar, respectivamente. Eles permitem criar interfaces consistentes que encapsulam controles de navegação e ação e que estão alinhadas com os princípios do Material Design.

Barras de apps na parte de cima

A tabela a seguir descreve os quatro tipos de barras de apps:

Tipo

Exemplo

Pequena: para telas que não exigem muita navegação ou ações.

Barra de apps superior pequena

Alinhada ao centro: para telas com uma única ação principal.

Barra de apps superior alinhada ao centro

Médio: para telas que exigem uma quantidade moderada de navegação e ações.

Barra de apps média na parte de cima

Grande: para telas que exigem muita navegação e ações.

Barra de apps superior grande

Superfície da API

Os vários elementos que permitem implementar as quatro barras de apps superiores são bastante semelhantes. Eles compartilham vários parâmetros importantes:

  • title: o texto que aparece na barra de apps.
  • navigationIcon: o ícone principal para navegação. Aparece à esquerda da barra de apps.
  • actions: ícones que dão ao usuário acesso às principais ações. Elas aparecem à direita da barra de apps.
  • scrollBehavior: determina como a barra de apps de cima responde à rolagem do conteúdo interno do scaffold.
  • colors: determina como a barra de apps aparece.

Comportamento de rolagem

É possível controlar como a barra de apps responde quando o usuário rola o conteúdo interno do scaffold. Para fazer isso, crie uma instância de TopAppBarScrollBehavior e transmita-a para a barra de apps de cima no parâmetro scrollBehavior.

Há três tipos de TopAppBarScrollBehavior. São eles:

  • enterAlwaysScrollBehavior: quando o usuário puxa o conteúdo interno do scaffold para cima, a barra de apps superior é recolhida. A barra de apps se expande quando o usuário começa a puxar o conteúdo interno para baixo.
  • exitUntilCollapsedScrollBehavior: semelhante a enterAlwaysScrollBehavior, mas a barra de apps só se expande quando o usuário puxa o conteúdo totalmente para baixo.
  • pinnedScrollBehavior: a barra de apps permanece no lugar e não reage à rolagem.

Os exemplos a seguir implementam várias dessas opções.

Exemplos

As seções a seguir mostram implementações para os quatro tipos diferentes de barras de apps de cima, incluindo vários exemplos de como controlar o comportamento de rolagem.

Pequeno

Para criar uma barra de apps pequena na parte de cima, use o elemento combinável TopAppBar. O exemplo a seguir implementa uma barra de apps de cima básica que contém apenas um título.

O exemplo a seguir não transmite a TopAppBar um valor para scrollBehavior e, portanto, não reage à rolagem do conteúdo interno.

@Composable
fun SmallTopAppBarExample() {
    Scaffold(
        topBar = {
            TopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text("Small Top App Bar")
                }
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}

Essa implementação é mostrada abaixo:

Figura 2. Uma barra de apps superior pequena.

Alinhada ao centro

A barra de apps de cima centralizada é basicamente igual à barra de apps pequena, mas o título fica centralizado no componente. Para implementar, use o combinável CenterAlignedTopAppBar dedicado.

Este exemplo usa enterAlwaysScrollBehavior() para receber o valor que ele transmite para scrollBehavior. Assim, a barra é recolhida quando o usuário rola o conteúdo interno do scaffold.

@Composable
fun CenterAlignedTopAppBarExample() {
    val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior(rememberTopAppBarState())

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),

        topBar = {
            CenterAlignedTopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text(
                        "Centered Top App Bar",
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis
                    )
                },
                navigationIcon = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Menu),
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}

Essa implementação é mostrada abaixo:

Figura 3. Uma barra de apps superior centralizada.

Médio

A barra de apps superior média coloca o título abaixo de todos os ícones adicionais. Para criar um, use o elemento combinável MediumTopAppBar.

Como o snippet anterior, este exemplo usa enterAlwaysScrollBehavior() para receber o valor que ele transmite para scrollBehavior.

@Composable
fun MediumTopAppBarExample() {
    val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior(rememberTopAppBarState())

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            MediumTopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text(
                        "Medium Top App Bar",
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis
                    )
                },
                navigationIcon = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Menu),
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}

Essa implementação aparece da seguinte forma, com uma demonstração de como o comportamento de rolagem de enterAlwaysScrollBehavior() aparece:

Figura 4. Uma barra de apps de tamanho médio que é recolhida quando o usuário rola para cima e expandida quando ele rola para baixo.

Grande

Uma barra de apps grande na parte de cima é semelhante à média, mas o padding entre o título e os ícones é maior e ela ocupa mais espaço na tela em geral. Para criar um, use o elemento combinável LargeTopAppBar.

Ao contrário dos snippets anteriores, este exemplo usa exitUntilCollapsedScrollBehavior() para receber o valor que ele transmite para scrollBehavior. Assim, a barra é recolhida quando o usuário rola o conteúdo interno do scaffold, mas se expande quando ele rola até o fim do conteúdo interno.

@Composable
fun LargeTopAppBarExample() {
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior(rememberTopAppBarState())

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            LargeTopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text(
                        "Large Top App Bar",
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis
                    )
                },
                navigationIcon = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Menu),
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}

Essa implementação é mostrada abaixo:

Figura 5. Exemplo de implementação de uma barra de apps superior grande.

Atualização do M3 Expressive

As novas barras de apps médias e grandes vêm com melhorias significativas, como alturas flexíveis, suporte a várias linhas e texto centralizado. Eles também podem conter uma variedade maior de elementos, como imagens. As barras de apps flexíveis médias e grandes são recomendadas em vez das barras de apps médias e grandes. A barra de apps pequena foi atualizada com as mesmas melhorias flexíveis.

Barras de apps na parte de cima com estilos expressivos.
Figura 6. Variações da barra de apps superior expressiva do M3.

Para mais informações sobre as atualizações do M3 Expressive para barras de apps, consulte as diretrizes de barras de apps do Material Design 3.

Alinhamento centralizado e à esquerda

Pequeno Barra de apps superior centralizada com subtítulo no tema claro
Barra de apps superior com tema escuro
Médio Barra de apps superior média com tema claro, alinhada ao centro e com subtítulo
Barra de apps superior média com tema escuro
Grande Barra de apps de cima grande, centralizada e com subtítulo no tema claro
Barra de apps superior grande com tema escuro

Os títulos pequenos, médios flexíveis e grandes flexíveis podem ser alinhados à borda inicial ou centralizados.

O snippet a seguir demonstra como implementar uma barra de apps de cima alinhada ao centro com um subtítulo:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun SimpleCenterAlignedTopAppBarWithSubtitle() {
    val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            TopAppBar(
                title = { Text("Simple TopAppBar", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                subtitle = { Text("Subtitle", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                titleHorizontalAlignment = Alignment.CenterHorizontally,
                navigationIcon = {
                    IconButton(onClick = { /* onBackClick() */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description",
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(painter = rememberVectorPainter(AppIcons.Favorite), contentDescription = "Localized description")
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
        content = { innerPadding ->
            // ...
        },
    )
}

Comportamento de rolagem

Sempre entrar

Quando o usuário rola o conteúdo para baixo (puxando o conteúdo para cima), a barra de apps é recolhida imediatamente. Quando o usuário rola para cima (puxando o conteúdo para baixo), a barra de apps se expande imediatamente, não importa onde o usuário esteja na lista de conteúdo rolável.

O snippet abaixo demonstra como implementar uma barra de apps de cima com comportamento de rolagem enter-always:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun EnterAlwaysTopAppBar() {
    val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            TopAppBar(
                title = { Text("TopAppBar", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                subtitle = { Text("Subtitle", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                navigationIcon = {
                    IconButton(onClick = { /* onBackClick() */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description",
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(painter = rememberVectorPainter(AppIcons.Favorite), contentDescription = "Localized description")
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
        content = { innerPadding ->
            // ...
        },
    )
}

O vídeo a seguir mostra o resultado do snippet anterior:

Figura 7. Uma barra de apps de cima com comportamento de rolagem "enter-always" que é recolhida quando o usuário rola para baixo e expandida quando ele rola para cima.

Sair até recolher

Quando o usuário rola o conteúdo para baixo (puxando o conteúdo para cima), as barras de apps flexíveis médias e grandes são recolhidas até que apenas a barra de apps recolhida permaneça visível. Quando o usuário rola para cima (puxando o conteúdo para baixo), a barra de apps permanece recolhida até que o usuário chegue ao topo do conteúdo. Nesse ponto, a barra de apps se expande de volta à altura total, centralizada com o subtítulo.

Flexibilidade média

O snippet abaixo demonstra como implementar uma barra de apps superior flexível média com comportamento de rolagem de saída até o recolhimento:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun ExitUntilCollapsedCenterAlignedMediumFlexibleTopAppBar() {
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            MediumFlexibleTopAppBar(
                title = { Text("Medium TopAppBar", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                subtitle = { Text("Subtitle", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                titleHorizontalAlignment = Alignment.CenterHorizontally,
                navigationIcon = {
                    IconButton(onClick = { /* onBackClick() */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description",
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(painter = rememberVectorPainter(AppIcons.Favorite), contentDescription = "Localized description")
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
        content = { innerPadding ->
            // ...
        },
    )
}

O vídeo a seguir mostra o resultado do snippet anterior:

Figura 8. Uma barra de apps superior de tamanho médio, alinhada ao centro, que é recolhida quando o usuário rola para baixo.

Grande flexível

O snippet abaixo demonstra como implementar uma barra de apps de cima flexível e grande com comportamento de rolagem de saída até o recolhimento:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun ExitUntilCollapsedCenterAlignedLargeFlexibleTopAppBar() {
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            LargeFlexibleTopAppBar(
                title = { Text("Large TopAppBar", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                subtitle = { Text("Subtitle", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                titleHorizontalAlignment = Alignment.CenterHorizontally,
                navigationIcon = {
                    IconButton(onClick = { /* onBackClick() */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.ArrowBack),
                            contentDescription = "Localized description",
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(painter = rememberVectorPainter(AppIcons.Favorite), contentDescription = "Localized description")
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
        content = { innerPadding ->
            // ...
        },
    )
}

O vídeo a seguir mostra o resultado do snippet anterior:

Figura 9. Uma barra de apps superior grande e centralizada que é recolhida quando o usuário rola para baixo.

Barra de apps inferior

Para criar uma barra de apps de fundo, use o elemento combinável BottomAppBar. O uso desse combinável é semelhante aos combináveis da barra de apps de cima descritos nas seções anteriores desta página. Você transmite elementos combináveis para os seguintes parâmetros principais:

  • actions: uma série de ícones que aparecem no lado esquerdo da barra. Normalmente, são ações importantes para a tela em questão ou itens de navegação.
  • floatingActionButton: o botão de ação flutuante que aparece no lado direito da barra.

@Composable
fun BottomAppBarExample() {
    Scaffold(
        bottomBar = {
            BottomAppBar(
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(painter = rememberVectorPainter(AppIcons.Check), contentDescription = "Localized description")
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Edit),
                            contentDescription = "Localized description",
                        )
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Mic),
                            contentDescription = "Localized description",
                        )
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            painter = rememberVectorPainter(AppIcons.Image),
                            contentDescription = "Localized description",
                        )
                    }
                },
                floatingActionButton = {
                    FloatingActionButton(
                        onClick = { /* do something */ },
                        containerColor = BottomAppBarDefaults.bottomAppBarFabColor,
                        elevation = FloatingActionButtonDefaults.bottomAppBarFabElevation()
                    ) {
                        Icon(painter = rememberVectorPainter(AppIcons.Add), "Localized description")
                    }
                }
            )
        },
    ) { innerPadding ->
        Text(
            modifier = Modifier.padding(innerPadding),
            text = "Example of a scaffold with a bottom app bar."
        )
    }
}

Essa implementação é mostrada abaixo:

Figura 10. Exemplo de implementação de uma barra de apps de fundo.

Atualização do M3 Expressive

Para o Material 3 Expressive, use a barra de ferramentas fixa (FlexibleBottomAppBar) em vez da barra de apps de baixo padrão para ter uma altura menor e uma disposição horizontal de itens mais flexível.

O snippet a seguir implementa uma FlexibleBottomAppBar com uma AppBarRow que move ações necessárias extras para um menu flutuante quando o espaço é limitado:

@Composable
fun FlexibleBottomAppBarSample() {
    val icons =
        listOf(
            AppIcons.ArrowBack,
            AppIcons.ArrowForward,
            AppIcons.Add,
            AppIcons.Check,
            AppIcons.Edit,
            AppIcons.Favorite,
        )
    val items = listOf("Back", "Forward", "Add", "Check", "Edit", "Favorite")

    FlexibleBottomAppBar(
        contentPadding = PaddingValues(horizontal = 96.dp),
        horizontalArrangement = BottomAppBarDefaults.FlexibleFixedHorizontalArrangement,
    ) {
        AppBarRow(
            overflowIndicator = { menuState ->
                IconButton(
                    onClick = {
                        if (menuState.isShowing) {
                            menuState.dismiss()
                        } else {
                            menuState.show()
                        }
                    }
                ) {
                    Icon(
                        painter = rememberVectorPainter(AppIcons.MoreVert),
                        contentDescription = "Overflow",
                    )
                }
            }
        ) {
            items.forEachIndexed { index, item ->
                clickableItem(
                    onClick = { /* doSomething() */ },
                    icon = {
                        Icon(
                            painter = rememberVectorPainter(icons[index]),
                            contentDescription = item,
                        )
                    },
                    label = item,
                )
            }
        }
    }
}

Outros recursos