Configura tu app con metadatos

En Navigation 3, usas metadatos para compartir información arbitraria entre diferentes componentes de la biblioteca, como NavEntry, Scene y NavDisplay. En su forma más básica, los metadatos son un Map<String, Any>. Sin embargo, la biblioteca proporciona abstracciones adicionales para que la lectura y la escritura de metadatos sean más sencillas y con mayor seguridad de tipos.

Proporciona metadatos de NavEntry

Si tu app compila sus instancias de NavEntry directamente, debes proporcionar metadatos para la entrada con el parámetro del constructor metadata:

when (key) {
    is Home -> NavEntry(key, metadata = mapOf("key" to "value")) {}
}
MetadataSnippets.kt

Si tu app usa el DSL de entryProvider, debes proporcionar metadatos a través del parámetro metadata de la función entry. Hay dos sobrecargas de esta función: una que toma un mapa directamente y otra que toma una lambda que pasa la clave de la entrada como un argumento:

entry<Home>(metadata = mapOf("key" to "value")) { /* ... */ }
entry<Conversation>(metadata = { key: Conversation ->
    mapOf("key" to "value: ${key.id})")
}) { /* ... */ }
MetadataSnippets.kt

Proporciona metadatos de Scene

De forma predeterminada, Scene.metadata usa un captador personalizado que devuelve el metadata de la última entrada en su propiedad entries o un mapa vacío si es null. Cuando implementes la interfaz Scene, puedes anular este comportamiento predeterminado según sea necesario.

Usa el DSL de metadatos

El lenguaje específico del dominio (DSL) de metadatos, que se introdujo en la versión 1.1.0-beta01 de la biblioteca, proporciona un compilador de acceso seguro a tipos para crear el objeto Map<String, Any> que se usa para almacenar metadatos.

Define claves de metadatos

El DSL se basa en la interfaz NavMetadataKey para mantener coherente el tipo del valor asociado con una clave de metadatos.

La convención para definir claves de metadatos es incluirlas como objetos anidados de la clase (o, en el caso de funciones o elementos componibles, un objeto relacionado) que leerá los valores asociados con esas claves:

// For classes such as scene strategies or nav entry decorators, you can define the keys
// as nested object.
class MySceneStrategy<T : Any> : SceneStrategy<T> {

    // ...

    object MyStringMetadataKey : NavMetadataKey<String>
}

// An example from NavDisplay.
// Because NavDisplay is a function, the metadata keys are defined in an object with the same name.
public object NavDisplay {

    public object TransitionKey :
        NavMetadataKey<AnimatedContentTransitionScope<Scene<*>>.() -> ContentTransform>
}
MetadataSnippets.kt

Compila metadatos con el DSL

Para crear un mapa de metadatos, usa la función metadata, que toma un parámetro lambda. Dentro de esta función lambda, usa la función put para agregar entradas al mapa con un NavMetadataKey y el valor correspondiente.

entry<Home>(
    metadata = metadata {
        put(NavDisplay.TransitionKey) { fadeIn() togetherWith fadeOut() }
        // An additional benefit of the metadata DSL is the ability to use conditional logic
        if (condition) {
            put(MySceneStrategy.MyStringMetadataKey, "Hello, world!")
        }
    }
) {
    // ...
}
MetadataSnippets.kt

Cómo leer metadatos con claves de metadatos

El DSL de metadatos también proporciona funciones para simplificar la lectura de metadatos con un NavMetadataKey.

// import androidx.navigation3.runtime.contains
// import androidx.navigation3.runtime.get

val hasMyString: Boolean = metadata.contains(MySceneStrategy.MyStringMetadataKey)
val myString: String? = metadata[MySceneStrategy.MyStringMetadataKey]
MetadataSnippets.kt