Barra de navegación

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

  • De tres a cinco destinos de igual importancia
  • Tamaños de ventana compactos
  • Destinos coherentes en 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.

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 está destacado visualmente.
  • onClick(): Es una función lambda obligatoria que define la acción que se realizará cuando el usuario haga clic en el elemento. Aquí es donde, por lo general, controlas los eventos de navegación, actualizas el estado del elemento seleccionado o cargas 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 en 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, en la que 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 expresión 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 los elementos 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:

Una pantalla de la app con 3 destinos enumerados horizontalmente en una barra de navegación inferior: Canciones, Álbum y Playlist. Cada destino tiene un ícono pertinente 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