Barras de apps

As barras de apps são contêineres que oferecem ao usuário acesso a recursos e itens de navegação importantes. Há dois tipos de barras de apps: as superiores e as inferiores. A aparência e a finalidade delas 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 hospeda um título, itens de ação principais e determinados itens de navegação.

Barra de apps da parte de baixo

Na parte de baixo da tela.

Normalmente inclui itens de navegação principais. Também pode oferecer acesso a outras ações importantes, como um botão de ação flutuante contido.
Exemplo de barra de apps superior e inferior.
Figura 1. Uma barra de apps superior (à esquerda) e uma barra de apps da parte de baixo (à direita).

Para implementar uma barra de apps superior e uma barra de apps da parte de baixo, use os TopAppBar e BottomAppBar combináveis, 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.

Barras de apps superiores

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

Tipo

Exemplo

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

 Barra de apps na parte de cima pequena

Alinhada ao centro: para telas que têm uma única ação principal.

 Barra de apps superior alinhada ao centro

Média: 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 superior grande

Superfície da API

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

  • title: o texto que aparece na barra de apps.
  • navigationIcon: o ícone principal de navegação. Aparece à esquerda da barra de apps.
  • actions: ícones que oferecem ao usuário acesso a ações importantes. Eles 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 do parâmetro scrollBehavior.

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

  • enterAlwaysScrollBehavior: quando o usuário puxa o conteúdo interno do scaffold, a barra de apps superior é recolhida. A barra de apps é expandida quando o usuário começa a puxar o conteúdo interno para baixo.
  • exitUntilCollapsedScrollBehavior: semelhante a enterAlwaysScrollBehavior, embora a barra de apps só seja expandida quando o usuário puxa o conteúdo até o fim.
  • 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 superiores, incluindo exemplos variados de como controlar o comportamento de rolagem.

Pequeno

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

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

Essa implementação aparece da seguinte maneira:

Exemplo de uma barra de apps superior pequena.
Figura 2. Uma barra de apps superior pequena.

Alinhada ao centro

A barra de apps superior alinhada ao centro é essencialmente a mesma que a barra de apps pequena, embora o título esteja centralizado no componente. Para implementá-lo, use o elemento combinável CenterAlignedTopAppBar dedicado.

Este exemplo usa enterAlwaysScrollBehavior() para receber 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.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)
    }
}
AppBar.kt

Essa implementação aparece da seguinte maneira:

Exemplo de uma barra de apps superior alinhada ao centro.
Figura 3. Uma barra de apps superior alinhada ao centro.

Médio

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

Como o 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 média que é recolhida quando o usuário rola para cima e expandida quando o usuário rola para baixo.

Grande

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

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 é expandida 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:

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

Barra de apps da parte de baixo

Para criar uma barra de apps da parte de baixo, use o elemento combinável BottomAppBar. O uso desse elemento combinável é bastante semelhante aos elementos combináveis da barra de apps superior 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. Essas são geralmente ações importantes para a tela 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 apps 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. Um exemplo de implementação de uma barra de apps da parte de baixo.

Outros recursos