Configurar o app com metadados

Na Navegação 3, você usa metadados para compartilhar informações arbitrárias entre diferentes componentes da biblioteca, como NavEntry, Scene e NavDisplay. No nível mais básico, metadados são um Map<String, Any>. No entanto, a biblioteca fornece outras abstrações para simplificar e tornar mais seguro o tipo de leitura e gravação de metadados.

Fornecer metadados de NavEntry

Se o app criar as instâncias de NavEntry diretamente, forneça metadados para a entrada usando o parâmetro do construtor metadata:

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

Se o app usar a DSL entryProvider, forneça metadados usando o parâmetro metadata da função entry. Há duas sobrecargas dessa função: uma que usa um mapa diretamente e outra que usa uma lambda que transmite a chave da entrada como um argumento:

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

Fornecer metadados de Scene

Por padrão, Scene.metadata usa um getter personalizado que retorna o metadata da última entrada na propriedade entries ou um mapa vazio se for null. Ao implementar a interface Scene, é possível substituir esse comportamento padrão conforme necessário.

Usar a DSL de metadados

Introduzida na versão 1.1.0-beta01 da biblioteca, a linguagem específica de domínio (DSL) de metadados fornece um builder com segurança de tipos para criar o Map<String, Any> usado para armazenar metadados.

Definir chaves de metadados

A DSL depende da interface NavMetadataKey para manter consistente o tipo do valor associado a uma chave de metadados.

A convenção para definir chaves de metadados é incluí-las como objetos aninhados da classe ou, no caso de funções ou elementos combináveis, um objeto relacionado que vai ler os valores associados a essas chaves:

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

Criar metadados usando a DSL

Para criar um mapa de metadados, use a função metadata, que recebe um parâmetro lambda. Nessa lambda, use a função put para adicionar entradas ao mapa usando um NavMetadataKey e o valor correspondente.

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

Ler metadados usando chaves de metadados

A DSL de metadados também oferece funções para simplificar a leitura de metadados com um 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