Barras de apps

As barras de apps 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.

Dá acesso às principais tarefas e informações. Geralmente, hospeda um título, itens de ação principais e determinados itens de navegação.

Barra de apps inferior

Na parte de baixo da tela.

Normalmente, inclui os itens de navegação principais. Também pode fornecer acesso a outras ações importantes, como um botão de ação flutuante.
Exemplo de uma barra de apps na parte de cima e de baixo.
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. Elas permitem criar interfaces consistentes que encapsulam controles de navegação e ação e que são alinhadas aos princípios do Material Design.

Principais barras de apps

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

Centralizada: 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 superior média

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

 Barra de apps grande na parte de cima

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. Eles são os seguintes:

  • enterAlwaysScrollBehavior: quando o usuário puxa o conteúdo interno do scaffold para cima, a barra de apps superior é fechada. 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 barra de apps pequena 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:

Exemplo de uma pequena barra de apps na parte de cima.
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.

Esse exemplo usa enterAlwaysScrollBehavior() para receber o valor transmitido para scrollBehavior. Dessa forma, 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:

Escreva o texto alternativo aqui
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:

Tela de um app com uma barra de apps na parte de baixo da tela com ícones de ação no lado esquerdo e um botão de ação flutuante à direita.
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 apps 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 para a tela especificada 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:

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

Outros recursos