Barra de navegación

La barra de navegación permite que los usuarios cambien entre destinos en una app. Deberías usar 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 "Label". El destino seleccionado aparece con un ícono de círculo, y el resto de los destinos, como triángulos.
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.

Superficie 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(): Define la acción que se realizará cuando el usuario haga clic en el elemento. La lógica para controlar los eventos de navegación, actualizar el estado del elemento seleccionado o cargar el contenido correspondiente pertenece aquí.
  • label: Muestra texto dentro del elemento. Opcional.
  • icon: Muestra un ícono dentro del elemento. Opcional.

Ejemplo: Barra de navegación inferior

En el siguiente fragmento, se 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))
    }
}

Puntos clave

  • NavigationBar muestra una colección de elementos, y cada uno 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.
    • 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.
  • La lógica de navegación llama al elemento de componibilidad 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 que resulta del fragmento anterior:

Una pantalla de la app con 3 destinos que se muestran de forma horizontal en una barra de navegación inferior: Songs, Album 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: Songs, Album y Playlist.

Recursos adicionales