Barra de navegação

A barra de navegação permite que os usuários alternem entre destinos 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 "Label". O destino selecionado aparece com um ícone de círculo, e os demais 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 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.

NavigationBarItem inclui os seguintes parâmetros principais:

  • selected: determina se o item atual está destacado visualmente.
  • 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 esse local.
  • label: mostra o 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))
    }
}

Pontos principais

  • NavigationBar mostra uma coleção de itens, em que cada item corresponde a um Destination.
  • val navController = rememberNavController() cria e lembra uma instância de NavHostController, que gerencia a navegação em um NavHost.
  • var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) } gerencia o estado do item selecionado.
    • startDestination.ordinal recebe o índice numérico (posição) da entrada do tipo enumerado 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 navController e 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:

Figura 2. Uma barra de navegação que contém três destinos com ícones associados: músicas, álbum e playlist.

Atualização do M3 Expressive

O Material 3 Expressive apresenta ShortNavigationBar e ShortNavigationBarItem como opções flexíveis adicionais, além do NavigationBar padrão.

Exemplo de uma barra de navegação flexível do Material 3, com altura menor e ícones com rótulos.
Figura 3. Uma barra de navegação flexível.

Para mais informações sobre as atualizações do M3 Expressive para barras de navegação, consulte as diretrizes da barra de navegação do Material Design 3.

Os itens de navegação em ShortNavigationBar podem ser organizados verticalmente ou horizontalmente.

Barra de navegação com itens verticais

Use itens verticais em janelas compactas, como em dispositivos móveis. O snippet abaixo demonstra como implementar um ShortNavigationBar com itens verticais:

@Composable
fun ShortNavigationBarSample() {
    var selectedItem by remember { mutableIntStateOf(0) }
    val items = listOf("Songs", "Artists", "Playlists")

    ShortNavigationBar {
        items.forEachIndexed { index, item ->
            ShortNavigationBarItem(
                icon = {
                    Icon(
                        painter = rememberVectorPainter(if (selectedItem == index) AppIcons.FavoriteFilled else AppIcons.Favorite),
                        contentDescription = null,
                    )
                },
                label = { Text(item) },
                selected = selectedItem == index,
                onClick = { selectedItem = index },
            )
        }
    }
}

Barra de navegação com itens horizontais

Use itens horizontais em janelas médias, como em tablets. O snippet abaixo demonstra como implementar uma ShortNavigationBar com itens horizontais centralizados na barra:

@Composable
fun ShortNavigationBarWithHorizontalItemsSample() {
    var selectedItem by remember { mutableIntStateOf(0) }
    val items = listOf("Songs", "Artists", "Playlists")

    Column {
        Text(
            "Note: this configuration is better displayed in medium screen sizes.",
            Modifier.padding(16.dp),
        )

        Spacer(Modifier.height(32.dp))

        ShortNavigationBar(arrangement = ShortNavigationBarArrangement.Centered) {
            items.forEachIndexed { index, item ->
                ShortNavigationBarItem(
                    iconPosition = NavigationItemIconPosition.Start,
                    icon = {
                        Icon(
                            painter = rememberVectorPainter(if (selectedItem == index) AppIcons.FavoriteFilled else AppIcons.Favorite),
                            contentDescription = null,
                        )
                    },
                    label = { Text(item) },
                    selected = selectedItem == index,
                    onClick = { selectedItem = index },
                )
            }
        }
    }
}

Outros recursos