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.

Oferece 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 de baixo

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 pequena na parte de cima

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 elas:

  • 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:

Exemplo de uma barra de apps de cima pequena.
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(
                            imageVector = Icons.AutoMirrored.Filled.ArrowBack,
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            imageVector = Icons.Filled.Menu,
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}

Essa implementação é mostrada abaixo:

Exemplo de uma barra de apps superior centralizada.
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(
                            imageVector = Icons.AutoMirrored.Filled.ArrowBack,
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            imageVector = Icons.Filled.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(
                            imageVector = Icons.AutoMirrored.Filled.ArrowBack,
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            imageVector = Icons.Filled.Menu,
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}

Essa implementação é mostrada abaixo:

Uma tela em um app com uma barra de apps na parte de baixo que contém quatro ícones de ação no lado esquerdo e um botão de ação flutuante no lado direito.
Figura 5. Exemplo de implementação de uma barra de apps superior grande.

Barra de apps de baixo

Para criar uma barra de apps de fundo, use o elemento combinável BottomAppBar. O uso desse combinável é bastante semelhante ao dos combináveis da barra de apps da parte de cima da tela descritos nas seções anteriores desta página. Você transmite elementos de composição 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(Icons.Filled.Check, contentDescription = "Localized description")
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            Icons.Filled.Edit,
                            contentDescription = "Localized description",
                        )
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            Icons.Filled.Mic,
                            contentDescription = "Localized description",
                        )
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            Icons.Filled.Image,
                            contentDescription = "Localized description",
                        )
                    }
                },
                floatingActionButton = {
                    FloatingActionButton(
                        onClick = { /* do something */ },
                        containerColor = BottomAppBarDefaults.bottomAppBarFabColor,
                        elevation = FloatingActionButtonDefaults.bottomAppBarFabElevation()
                    ) {
                        Icon(Icons.Filled.Add, "Localized description")
                    }
                }
            )
        },
    ) { innerPadding ->
        Text(
            modifier = Modifier.padding(innerPadding),
            text = "Example of a scaffold with a bottom app bar."
        )
    }
}

Essa implementação é mostrada abaixo:

Uma tela em um app com uma barra de apps na parte de baixo que contém quatro ícones de ação no lado esquerdo e um botão de ação flutuante no lado direito.
Figura 6. Exemplo de implementação de uma barra de apps de fundo.

Outros recursos