Barra de navegación

La barra de navegación permite que los usuarios cambien de destino en una app. Debes usar las 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 componible 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:

Figura 2. Una barra de navegación que contiene 3 destinos con íconos asociados: Songs, Album y Playlist.

Actualización de M3 Expressive

Material 3 Expressive presenta ShortNavigationBar y ShortNavigationBarItem como opciones adicionales y flexibles junto con el NavigationBar estándar.

Ejemplo de una barra de navegación flexible de Material 3, con una altura más corta y con íconos con etiquetas.
Figura 3: Una barra de navegación flexible

Para obtener más información sobre las actualizaciones de M3 Expressive para las barras de navegación, consulta los lineamientos de la barra de navegación de Material Design 3.

Los elementos de navegación de ShortNavigationBar se pueden organizar de forma vertical o horizontal.

Barra de navegación con elementos verticales

Usa elementos verticales en ventanas compactas, como en dispositivos móviles. En el siguiente fragmento, se muestra cómo implementar un ShortNavigationBar con elementos verticales:

@Composable
fun ShortNavigationBarSample() {
    var selectedItem by remember { mutableIntStateOf(0) }
    val items = listOf("Songs", "Artists", "Playlists")

    ShortNavigationBar {
        items.forEachIndexed { index, item ->
            ShortNavigationBarItem(
                icon = {
                    Icon(
                        painter = rememberVectorPainter(if (selectedItem == index) AppIcons.FavoriteFilled else AppIcons.Favorite),
                        contentDescription = null,
                    )
                },
                label = { Text(item) },
                selected = selectedItem == index,
                onClick = { selectedItem = index },
            )
        }
    }
}

Barra de navegación con elementos horizontales

Usa elementos horizontales en ventanas medianas, como en tablets. En el siguiente fragmento, se muestra cómo implementar un ShortNavigationBar con elementos horizontales centrados en la barra:

@Composable
fun ShortNavigationBarWithHorizontalItemsSample() {
    var selectedItem by remember { mutableIntStateOf(0) }
    val items = listOf("Songs", "Artists", "Playlists")

    Column {
        Text(
            "Note: this configuration is better displayed in medium screen sizes.",
            Modifier.padding(16.dp),
        )

        Spacer(Modifier.height(32.dp))

        ShortNavigationBar(arrangement = ShortNavigationBarArrangement.Centered) {
            items.forEachIndexed { index, item ->
                ShortNavigationBarItem(
                    iconPosition = NavigationItemIconPosition.Start,
                    icon = {
                        Icon(
                            painter = rememberVectorPainter(if (selectedItem == index) AppIcons.FavoriteFilled else AppIcons.Favorite),
                            contentDescription = null,
                        )
                    },
                    label = { Text(item) },
                    selected = selectedItem == index,
                    onClick = { selectedItem = index },
                )
            }
        }
    }
}

Recursos adicionales