Riel de navegación

Los rieles proporcionan acceso a los destinos en las apps que se ejecutan en dispositivos con pantallas grandes. Deberías usar rieles de navegación para lo siguiente:

  • Destinos de nivel superior a los que se debe poder acceder desde cualquier lugar de una app
  • De tres a siete destinos principales
  • Diseños para tablets o computadoras de escritorio
Un riel de navegación vertical en el lado izquierdo de una pantalla con cuatro destinos (Todos los archivos, Recientes, Fotos y Biblioteca), cada uno con un ícono asociado, y un botón de acción flotante.
Figura 1: Un riel de navegación con cuatro destinos y un botón de acción flotante.

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

Superficie de la API

Usa el elemento componible NavigationRail con NavigationRailItem para implementar un riel en tu aplicación. El NavigationRailItem representa un solo elemento de riel en la columna de riel.

NavigationRailItem incluye los siguientes parámetros clave:

  • selected: Determina si el elemento de riel 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 de la barra lateral. Aquí es donde sueles controlar los eventos de navegación, actualizar el estado del elemento de riel seleccionado o cargar el contenido correspondiente.
  • label: Muestra texto dentro del elemento de riel. Opcional.
  • icon: Muestra un ícono dentro del elemento de riel. Opcional.

Ejemplo: Navegación basada en rieles

En el siguiente fragmento, se implementa un riel de navegación para que los usuarios puedan navegar entre diferentes pantallas de una app:

@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)
    }
}

Puntos clave

  • NavigationRail muestra una columna vertical de elementos de riel, 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 de riel 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 del riel, se llama a navController.navigate(route = destination.route) para navegar a la pantalla correspondiente.
  • La lambda onClick de NavigationRailItem actualiza el estado selectedDestination para destacar visualmente el elemento del riel en el que se hizo clic.
  • 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 el resultado del fragmento anterior:

Un riel de navegación vertical con 3 destinos con íconos asociados: Songs, Album y Playlist. Los íconos indican visualmente el propósito de cada botón de navegación en el riel. Cada destino tiene un ícono relevante asociado (p.ej., una nota musical para "Canciones").
Figura 2: Un riel de navegación que contiene 3 destinos con íconos asociados: Songs, Album y Playlist.

Recursos adicionales