Barras de apps

As barras de app são contêineres que fornecem ao usuário acesso aos principais recursos e itens de navegação. Há dois tipos de barras de apps: na parte de cima e na parte de baixo. A aparência e a finalidade deles são as seguintes:

Tipo	Aparência	Objetivo
Barra de apps superior	Na parte de cima da tela.	Permite acesso a tarefas e informações importantes. Geralmente hospeda um título, itens de ação principais e alguns itens de navegação.
Barra de apps inferior	Na parte de baixo da tela.	Normalmente, inclui os itens principais de navegação. Também pode fornecer acesso a outras ações importantes, como um botão de ação flutuante.

Figura 1. Uma barra de apps na parte de cima (esquerda) e uma na parte de baixo (direita).

Para implementar uma barra de apps na parte de cima e 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 aos princípios do Material Design.

Importante: as barras de app geralmente são transmitidas para o elemento combinável Scaffold, que tem parâmetros específicos para recebê-las. Para mais informações sobre como o Scaffold oferece uma maneira conveniente de estruturar seu app, acesse a página Scaffold.

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.
Centralizada: para telas com uma única ação principal.
Médio: para telas que exigem uma quantidade moderada de navegação e ações.
Grande: para telas que exigem muita navegação e ações.

Superfície da API

Os vários elementos combináveis que permitem implementar as quatro barras de apps 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 a ações importantes. Elas aparecem à direita da barra de apps.
• scrollBehavior: determina como a barra de apps superior 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 superior para o parâmetro scrollBehavior.

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

• enterAlwaysScrollBehavior: quando o usuário puxa o conteúdo interno do scaffold, a barra de apps superior é recolhida. A barra de apps se expande quando o usuário puxa o conteúdo interno para baixo.
• exitUntilCollapsedScrollBehavior: semelhante a enterAlwaysScrollBehavior, mas a barra de apps também se expande quando o usuário chega ao fim do conteúdo interno do scaffold.
• 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 fornecem implementações para os quatro tipos diferentes de barras de apps na parte de cima, incluindo exemplos variados de como controlar o comportamento de rolagem.

Pequeno

Para criar uma pequena barra de apps na parte de cima, use o elemento combinável TopAppBar. Essa é a barra de apps de cima mais simples possível e, neste exemplo, contém apenas um título.

O exemplo a seguir não transmite um valor de TopAppBar 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)
    }
}
AppBar.kt

Essa implementação aparece da seguinte maneira:

Figura 2. Uma pequena barra de apps na parte de cima.

Alinhado ao centro

A barra de apps superior alinhada ao centro é basicamente a mesma que a pequena, mas o título fica centralizado no componente. Para implementar, use o elemento combinável dedicado CenterAlignedTopAppBar.

Este exemplo usa enterAlwaysScrollBehavior() para acessar o valor transmitido 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.centerAlignedTopAppBarColors(
                    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)
    }
}
AppBar.kt

Essa implementação aparece da seguinte maneira:

Figura 3. Uma barra de apps superior centralizada.

Médio

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

Como no snippet anterior, este exemplo usa enterAlwaysScrollBehavior() para receber o valor transmitido 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)
    }
}
AppBar.kt

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

Figura 4. Uma barra de apps superior centralizada.

Grande

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

Ao contrário dos snippets anteriores, este exemplo usa exitUntilCollapsedScrollBehavior() para receber o valor transmitido para scrollBehavior. Assim, a barra é recolhida quando o usuário rola o conteúdo interno do scaffold, mas se expande quando o usuário rola até o final 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)
    }
}
AppBar.kt

Essa implementação aparece da seguinte maneira:

Figura 5. Exemplo de implementação de uma barra de apps grande na parte de cima.

Barra de apps inferior

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

• actions: uma série de ícones que aparecem no lado esquerdo da barra. Geralmente, são ações principais da 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."
        )
    }
}
AppBar.kt

Essa implementação aparece da seguinte maneira:

Figura 6. Exemplo de implementação de uma barra de apps inferior.

Observação: também é possível usar BottomAppBar sem transmitir um valor para actions e floatingActionButton. Nesse caso, é possível criar uma barra de app inferior personalizada preenchendo BottomAppBar com conteúdo, como faria com outros contêineres.

Outros recursos

• Documentação do Material3: barra de apps na parte de cima
• Documentação do Material3: barra de apps na parte de baixo
• Scaffold