Barra de navegación

La barra de navegación permite a los usuarios cambiar entre destinos en una app. Debes usar las barras de navegación para lo siguiente:

  • De tres a cinco destinos de igual importancia
  • Tamaños de ventana compactos
  • Destinos coherentes en todas las pantallas de la app
Una barra de navegación con 4 destinos. Cada destino tiene un nombre de marcador de posición llamado
Figura 1: Una barra de navegación con 4 destinos.

En esta página, se muestra cómo mostrar una barra de navegación en tu app con pantallas relacionadas y navegación básica.

Plataforma de la API

Usa los elementos componibles NavigationBar y NavigationBarItem para implementar la lógica de cambio de destino. Cada NavigationBarItem representa un destino único.

NavigationBarItem incluye los siguientes parámetros clave:

  • selected: Determina si el elemento actual se destaca visualmente.
  • onClick(): Es una función lambda obligatoria que define la acción que se realizará cuando el usuario haga clic en el elemento. Por lo general, es aquí donde se controlan los eventos de navegación, se actualiza el estado del elemento seleccionado o se carga el contenido correspondiente.
  • label: Muestra texto dentro del elemento. Opcional.
  • icon: Muestra un ícono dentro del elemento. Opcional.

Ejemplo: Barra de navegación inferior

El siguiente fragmento implementa una barra de navegación inferior con elementos para que los usuarios puedan navegar entre diferentes pantallas de una 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

Puntos clave

  • NavigationBar muestra una colección de elementos, y cada elemento corresponde a un Destination.
  • val navController = rememberNavController() crea y recuerda una instancia de NavHostController, que administra la navegación dentro de un NavHost.
  • var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) } administra el estado del elemento seleccionado actualmente.
  • var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) } administra el estado del elemento seleccionado actualmente.
    • startDestination.ordinal obtiene el índice numérico (posición) de la entrada de enumeración Destination.SONGS.
  • Cuando se hace clic en un elemento, se llama a navController.navigate(route = destination.route) para navegar a la pantalla correspondiente.
  • La lambda onClick de NavigationBarItem actualiza el estado selectedDestination para destacar visualmente el elemento en el que se hizo clic.
  • Llama al elemento componible AppNavHost y pasa navController y startDestination para mostrar el contenido real de la pantalla seleccionada.

Resultado

En la siguiente imagen, se muestra la barra de navegación resultante del fragmento anterior:

Pantalla de una app con 3 destinos en una barra de navegación inferior: Canciones, Álbumes y Playlist. Cada destino tiene un ícono relevante asociado (p.ej., una nota musical para “Canciones”).
Figura 2: Una barra de navegación que contiene 3 destinos con íconos asociados: Canciones, Álbum y Playlist.

Recursos adicionales