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 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 NavigationRail componible 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 del carril 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 del 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 del carril. Opcional.
  • icon: Muestra un ícono dentro del elemento del riel. Opcional.

Ejemplo: Navegación basada en rieles

El siguiente fragmento implementa un riel de navegación para que los usuarios puedan navegar entre diferentes pantallas en 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 del carril, 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 transporte público 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 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 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 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: Canciones, Álbum y Playlist.

Recursos adicionales