Riel de navegación

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

  • Destinos de nivel superior que deben ser accesibles en cualquier lugar de una app
  • De tres a siete destinos principales
  • Diseños para tablets o computadoras
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. NavigationRailItem representa un solo elemento de riel en la columna del riel.

NavigationRailItem incluye los siguientes parámetros clave:

  • selected: Determina si el elemento de riel actual está resaltado 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 riel. Aquí es donde, por lo general, controlas los eventos de navegación, actualizas el estado del elemento de riel seleccionado o cargas el contenido correspondiente.
  • label: Muestra texto dentro del elemento de riel. Es opcional.
  • icon: Muestra un ícono dentro del elemento de riel. Es 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)
    }
}
Navigation.kt

Puntos clave

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

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

Recursos adicionales