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
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
NavigationBarmostra uma coleção de itens, em que cada item corresponde a umDestination.val navController = rememberNavController()cria e lembra uma instância deNavHostController, que gerencia a navegação em umNavHost.var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) }gerencia o estado do item selecionado.startDestination.ordinalrecebe o índice numérico (posição) da entrada do tipo enumeradoDestination.SONGS.
- Quando um item é clicado,
navController.navigate(route = destination.route)é chamado para navegar até a tela correspondente. - A lambda
onClickdoNavigationBarItematualiza o estadoselectedDestinationpara destacar visualmente o item clicado. - A lógica de navegação chama o elemento combinável
AppNavHost, transmitindonavControllerestartDestination, para mostrar o conteúdo real da tela selecionada.
Resultado
A imagem a seguir mostra a barra de navegação resultante do snippet anterior:
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.
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 }, ) } } } }