Barra de navegação

A barra de navegação permite que os usuários troquem de destino em um app. Use barras de navegação para:

  • Três a cinco destinos de igual importância
  • Tamanhos de janela compactos
  • Destinos consistentes em todas as telas do app
Uma barra de navegação com quatro destinos. Cada destino tem um nome de marcador de posição chamado "Rótulo". O destino selecionado aparece com um ícone de círculo, e os outros destinos aparecem como triângulos.
Figura 1. Uma barra de navegação com quatro destinos.

Nesta página, mostramos como exibir uma barra de navegação no seu app com telas relacionadas e navegação básica.

Superfície da API

Use os elementos combináveis NavigationBar e NavigationBarItem para implementar a lógica de troca de destino. Cada NavigationBarItem representa um destino único.

O NavigationBarItem inclui os seguintes parâmetros principais:

  • selected: determina se o item atual está visualmente destacado.
  • onClick(): define a ação a ser realizada quando o usuário clica no item. A lógica para processar eventos de navegação, atualizar o estado do item selecionado ou carregar o conteúdo correspondente pertence a este lugar.
  • label: mostra texto dentro do item. Opcional.
  • icon: mostra um ícone no item. Opcional.

Exemplo: barra de navegação na parte de baixo

O snippet a seguir implementa uma barra de navegação na parte de baixo com itens para que os usuários possam navegar entre diferentes telas em um app:

@Composable
fun NavigationBarExample(modifier: Modifier = Modifier) {
    val navController = rememberNavController()
    val startDestination = Destination.SONGS
    var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) }

    Scaffold(
        modifier = modifier,
        bottomBar = {
            NavigationBar(windowInsets = NavigationBarDefaults.windowInsets) {
                Destination.entries.forEachIndexed { index, destination ->
                    NavigationBarItem(
                        selected = selectedDestination == index,
                        onClick = {
                            navController.navigate(route = destination.route)
                            selectedDestination = index
                        },
                        icon = {
                            Icon(
                                destination.icon,
                                contentDescription = destination.contentDescription
                            )
                        },
                        label = { Text(destination.label) }
                    )
                }
            }
        }
    ) { contentPadding ->
        AppNavHost(navController, startDestination, modifier = Modifier.padding(contentPadding))
    }
}
Navigation.kt

Pontos principais

  • NavigationBar mostra uma coleção de itens, em que cada um corresponde a um Destination.
  • O val navController = rememberNavController() cria e lembra de uma instância de NavHostController, que gerencia a navegação em um NavHost.
  • O var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) } gerencia o estado do item selecionado.
    • startDestination.ordinal recebe o índice numérico (posição) da entrada de enumeração Destination.SONGS.
  • Quando um item é clicado, navController.navigate(route = destination.route) é chamado para navegar até a tela correspondente.
  • A lambda onClick do NavigationBarItem atualiza o estado selectedDestination para destacar visualmente o item clicado.
  • A lógica de navegação chama o elemento combinável AppNavHost, transmitindo o navController e o startDestination, para mostrar o conteúdo real da tela selecionada.

Resultado

A imagem a seguir mostra a barra de navegação resultante do snippet anterior:

Uma tela de app com três destinos listados horizontalmente em uma barra de navegação inferior: "Músicas", "Álbum" e "Playlist". Cada destino tem um ícone relevante associado a ele (por exemplo, uma nota musical para "Músicas").
Figura 2. Uma barra de navegação com três destinos e ícones associados: "Músicas", "Álbum" e "Playlist".

Outros recursos