Coluna de navegação

As barras de navegação dão acesso a destinos em apps executados em dispositivos com telas grandes. Use as colunas de navegação para:

• Destinos de nível superior que precisam ser acessíveis em qualquer lugar de um app
• De três a sete destinos principais
• Layouts para tablet ou computador

Figura 1. Uma coluna de navegação com quatro destinos e um botão de ação flutuante.

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

Superfície da API

Use o elemento combinável NavigationRail com NavigationRailItem para implementar uma coluna de navegação no seu aplicativo. O NavigationRailItem representa um único item na coluna de coluna.

O NavigationRailItem inclui os seguintes parâmetros principais:

• selected: determina se o item atual da barra de navegação está destacado visualmente.
• onClick(): uma função lambda obrigatória que define a ação a ser executada quando o usuário clica no item da coluna. É aqui que você geralmente processa eventos de navegação, atualiza o estado do item selecionado na coluna ou carrega o conteúdo correspondente.
• label: mostra o texto dentro do item da coluna. Opcional.
• icon: mostra um ícone no item da coluna. Opcional.

Exemplo: navegação baseada em trilhos

O snippet a seguir implementa uma coluna de navegação para que os usuários possam navegar entre diferentes telas em um app:

Observação: o código-fonte completo inclui o código que estabelece a estrutura de navegação básica para o exemplo a seguir.

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

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

Pontos principais

• NavigationRail mostra uma coluna vertical de itens de coluna, 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 de coluna selecionado.
  • startDestination.ordinal recebe o índice numérico (posição) da entrada do tipo enumerado Destination.SONGS.
• Quando um item da coluna é clicado, navController.navigate(route = destination.route) é chamado para navegar até a tela correspondente.
• A lambda onClick do NavigationRailItem atualiza o estado selectedDestination para destacar visualmente o item da coluna clicado.
• Ele 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 o resultado do snippet anterior:

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

Outros recursos

• Material 3: coluna de navegação
• Navegação com o Compose