Comprende y, luego, implementa los conceptos básicos

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

La navegación describe la forma en que los usuarios se mueven por tu app. Los usuarios interactúan con los elementos de la IU, por lo general, presionando o haciendo clic en ellos, y la app responde mostrando contenido nuevo. Si el usuario quiere volver al contenido anterior, usa el gesto atrás o presiona el botón Atrás.

Cómo modelar el estado de navegación

Una forma conveniente de modelar este comportamiento es con una pila de contenido. A medida que el usuario navega hacia adelante hacia contenido nuevo, este se envía a la parte superior de la pila. Cuando regresan de ese contenido, se quita de la pila y se muestra el contenido anterior. En términos de navegación, esta pila suele denominarse pila de actividades porque representa el contenido al que el usuario puede volver.

Crea una pila de actividades

En Navigation 3, la pila de actividades no contiene contenido. En su lugar, contiene referencias al contenido, conocidas como claves. Las claves pueden ser de cualquier tipo, pero suelen ser clases de datos simples y serializables. El uso de referencias en lugar de contenido tiene los siguientes beneficios:

• Es fácil navegar presionando teclas en la pila de actividades.
• Siempre que las claves sean serializables, la pila de actividades se puede guardar en el almacenamiento persistente, lo que le permite sobrevivir a los cambios de configuración y al proceso de finalización. Esto es importante porque los usuarios esperan salir de tu app, volver a ella más adelante y retomar desde donde dejaron con el mismo contenido que se muestra. Consulta Cómo guardar tu pila de actividades para obtener más información.

Un concepto clave en la API de Navigation 3 es que eres propietario de la pila de actividades. La biblioteca hace lo siguiente:

• Se espera que tu pila de actividades sea un List<T> con copia de seguridad del estado de instantánea, en el que T es el tipo de tu pila de actividades keys. Puedes usar Any o proporcionar tus propias claves con un tipo más estricto. Cuando ves los términos "push" o "pop", la implementación subyacente es agregar o quitar elementos del final de una lista.
• Observa tu pila de actividades y refleja su estado en la IU con un NavDisplay.

En el siguiente ejemplo, se muestra cómo crear claves y una pila de actividades, y modificar la pila de actividades en respuesta a eventos de navegación del usuario:

// Define keys that will identify content
data object ProductList
data class ProductDetail(val id: String)

@Composable
fun MyApp() {

    // Create a back stack, specifying the key the app should start with
    val backStack = remember { mutableStateListOf<Any>(ProductList) }

    // Supply your back stack to a NavDisplay so it can reflect changes in the UI
    // ...more on this below...

    // Push a key onto the back stack (navigate forward), the navigation library will reflect the change in state
    backStack.add(ProductDetail(id = "ABC"))

    // Pop a key off the back stack (navigate back), the navigation library will reflect the change in state
    backStack.removeLastOrNull()
}
BasicSnippets.kt

Cómo resolver las claves del contenido

El contenido se modela en Navigation 3 con NavEntry, que es una clase que contiene una función componible. Representa un destino, un solo elemento de contenido al que el usuario puede navegar y regresar.

Un NavEntry también puede contener metadatos, es decir, información sobre el contenido. Los objetos de contenedor, como NavDisplay, pueden leer estos metadatos para ayudarlos a decidir cómo mostrar el contenido de NavEntry. Por ejemplo, los metadatos se pueden usar para anular las animaciones predeterminadas de un NavEntry específico. NavEntrymetadata es un mapa de claves String a valores Any, lo que proporciona un almacenamiento de datos versátil.

Para convertir un key en un NavEntry, crea un entryProvider. Esta es una función que acepta un key y muestra un NavEntry para ese key. Por lo general, se define como un parámetro lambda cuando se crea un NavDisplay.

Existen dos maneras de crear un entryProvider: creando una función lambda directamente o usando la DSL de entryProvider.

Crea una función entryProvider directamente

Por lo general, creas una función entryProvider con una sentencia when, con una rama para cada una de tus claves.

entryProvider = { key ->
    when (key) {
        is ProductList -> NavEntry(key) { Text("Product List") }
        is ProductDetail -> NavEntry(
            key,
            metadata = mapOf("extraDataKey" to "extraDataValue")
        ) { Text("Product ${key.id} ") }

        else -> {
            NavEntry(Unit) { Text(text = "Invalid Key: $it") }
        }
    }
}
BasicSnippets.kt

Usa la DSL de entryProvider

La DSL de entryProvider puede simplificar tu función lambda, ya que evita la necesidad de probar cada uno de tus tipos de claves y construir un NavEntry para cada uno. Para ello, usa la función del compilador entryProvider. También incluye el comportamiento de resguardo predeterminado (genera un error) si no se encuentra la clave.

entryProvider = entryProvider {
    entry<ProductList> { Text("Product List") }
    entry<ProductDetail>(
        metadata = mapOf("extraDataKey" to "extraDataValue")
    ) { key -> Text("Product ${key.id} ") }
}
BasicSnippets.kt

Ten en cuenta lo siguiente del fragmento:

• entry se usa para definir un NavEntry con el tipo y el contenido componible especificados.
• entry acepta un parámetro metadata para establecer NavEntry.metadata.

Cómo mostrar la pila de actividades

La pila de actividades representa el estado de navegación de tu app. Cada vez que cambia la pila de actividades, la IU de la app debe reflejar el nuevo estado de la pila. En Navigation 3, un NavDisplay observa tu pila de actividades y actualiza su IU según corresponda. Cónstruyela con los siguientes parámetros:

• Tu pila de actividades, que debe ser del tipo SnapshotStateList<T>, en el que T es el tipo de tus claves de pila de actividades. Es un List observable para que active la recomposición de NavDisplay cuando cambie.
• Un entryProvider para convertir las claves de tu pila de actividades en NavEntry.
• De manera opcional, proporciona una lambda al parámetro onBack. Se llama cuando el usuario activa un evento de atrás.

En el siguiente ejemplo, se muestra cómo crear un NavDisplay.

data object Home
data class Product(val id: String)

@Composable
fun NavExample() {

    val backStack = remember { mutableStateListOf<Any>(Home) }

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        entryProvider = { key ->
            when (key) {
                is Home -> NavEntry(key) {
                    ContentGreen("Welcome to Nav3") {
                        Button(onClick = {
                            backStack.add(Product("123"))
                        }) {
                            Text("Click to navigate")
                        }
                    }
                }

                is Product -> NavEntry(key) {
                    ContentBlue("Product ${key.id} ")
                }

                else -> NavEntry(Unit) { Text("Unknown route") }
            }
        }
    )
}
BasicSnippets.kt

De forma predeterminada, NavDisplay muestra el NavEntry más alto en la pila de actividades en un diseño de un solo panel. En la siguiente grabación, se muestra esta app en ejecución:

Resumen

En el siguiente diagrama, se muestra cómo fluyen los datos entre los diversos objetos de Navigation 3:

1. Los eventos de navegación inician cambios. Las claves se agregan o quitan de la pila de actividades en respuesta a las interacciones del usuario.

2. El cambio en el estado de la pila de actividades activa la recuperación de contenido. NavDisplay (un elemento componible que renderiza una pila de actividades) observa la pila de actividades. En su configuración predeterminada, muestra la entrada de pila de actividades más alta en un diseño de panel único. Cuando cambia la clave superior de la pila de actividades, NavDisplay usa esta clave para solicitar el contenido correspondiente al proveedor de entrada.

3. El proveedor de entradas proporciona contenido. El proveedor de entrada es una función que resuelve una clave en una NavEntry. Cuando recibe una clave del NavDisplay, el proveedor de entradas proporciona el NavEntry asociado, que contiene la clave y el contenido.

4. Se muestra el contenido. NavDisplay recibe NavEntry y muestra el contenido.