Configurare l'app con i metadati

In Navigation 3, utilizzi i metadati per condividere informazioni arbitrarie tra diversi componenti della libreria, come NavEntry, Scene e NavDisplay. Nella sua forma più semplice, i metadati sono un Map<String, Any>. Tuttavia, la libreria fornisce astrazioni aggiuntive per semplificare e rendere più sicura la lettura e la scrittura dei metadati.

Fornisci i metadati NavEntry

Se la tua app crea direttamente le istanze NavEntry, fornisci i metadati per la voce utilizzando il parametro del costruttore metadata:

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

Se la tua app utilizza il entryProvider DSL, fornisci i metadati tramite il parametro metadata della funzione entry. Esistono due overload di questa funzione: uno che accetta direttamente una mappa e un altro che accetta una lambda che passa la chiave della voce come argomento:

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

Fornisci i metadati Scene

Per impostazione predefinita, Scene.metadata utilizza un getter personalizzato che restituisce metadata dell'ultima voce nella proprietà entries o una mappa vuota se null. Quando implementi l'interfaccia Scene, puoi eseguire l'override di questo comportamento predefinito in base alle esigenze.

Utilizzare il DSL dei metadati

Introdotta nella release 1.1.0-beta01 della libreria, la lingua specifica del dominio (DSL) dei metadati fornisce un builder type-safe per creare Map<String, Any> utilizzato per archiviare i metadati.

Definisci le chiavi dei metadati

Il linguaggio DSL si basa sull'interfaccia NavMetadataKey per mantenere coerente il tipo di valore associato a una chiave di metadati.

La convenzione per definire le chiavi dei metadati è includerle come oggetti nidificati della classe o, nel caso di funzioni o composable, un oggetto correlato che leggerà i valori associati a queste chiavi:

// 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

Creare metadati utilizzando il DSL

Per creare una mappa dei metadati, utilizza la funzione metadata, che accetta un parametro lambda. All'interno di questa funzione lambda, utilizza la funzione put per aggiungere voci alla mappa utilizzando un NavMetadataKey e il valore corrispondente.

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

Leggere i metadati utilizzando le chiavi dei metadati

Il DSL dei metadati fornisce anche funzioni per semplificare la lettura dei metadati 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