Appliquer une logique ou des wrappers aux destinations

Vous pouvez fournir des informations supplémentaires ou appliquer la même logique aux destinations à l'aide de la classe NavEntryDecorator. Cette classe encapsule chaque NavEntry dans une pile "Retour" avec une fonction composable. En d'autres termes, il décore le contenu de l'entrée.

Créer un décorateur personnalisé

Pour créer un décorateur, étendez la classe NavEntryDecorator et remplacez les méthodes suivantes :

• decorate : lambda composable appelé pour chaque NavEntry de votre pile "Retour". Il reçoit NavEntry en tant que paramètre. Cela vous permet de créer des objets d'état associés à l'contentKey de l'entrée. Vous pouvez utiliser CompositionLocalProvider pour fournir des dépendances au contenu de l'entrée. Vous pouvez également entourer le contenu d'une fonction composable ou déclencher des effets secondaires. Vous devez toujours appeler entry.Content() dans cette méthode.
• onPop : rappel qui est appelé lorsqu'un NavEntry a été supprimé de la pile "Retour" et a quitté la composition. Il reçoit le contentKey de l'entrée supprimée. Utilisez le contentKey pour identifier et nettoyer tout état associé à cette entrée.

L'exemple suivant étend la classe NavEntryDecorator pour créer un décorateur personnalisé.

// import androidx.navigation3.runtime.NavEntryDecorator
class CustomNavEntryDecorator<T : Any> : NavEntryDecorator<T>(
    decorate = { entry ->
        Log.d("CustomNavEntryDecorator", "entry with ${entry.contentKey} entered composition and was decorated")
        entry.Content()
    },
    onPop = { contentKey -> Log.d("CustomNavEntryDecorator", "entry with $contentKey was popped") }
)
DecoratorSnippets.kt

Si votre décorateur a besoin d'accéder à l'état, créez une fonction composable qui crée cet état, puis utilisez-le pour construire le décorateur. Pour obtenir un exemple d'implémentation, consultez le code source de rememberSaveableStateHolderNavEntryDecorator. Cela crée l'état (un SaveableStateHolder) et l'utilise pour construire le décorateur.

Décorer une pile "Retour"

Une fois que vous avez créé votre NavEntryDecorator, décorez les entrées de votre pile de retour de l'une des deux manières suivantes :

• Utilisez rememberDecoratedNavEntries. Cette fonction est utile lorsque vous avez plusieurs piles "Retour", chacune avec son propre ensemble de décorateurs (consultez cette recette de code pour en savoir plus). La fonction renvoie une liste décorée de NavEntry que vous pouvez utiliser avec NavDisplay.
• Fournissez votre décorateur directement à NavDisplay à l'aide du paramètre entryDecorators. NavDisplay appelle rememberDecoratedNavEntries en arrière-plan et affiche les entrées décorées.

Inclure le décorateur par défaut

Navigation 3 inclut un décorateur par défaut nommé SaveableStateHolderNavEntryDecorator qui permet de conserver l'état d'un NavEntry en cas de changement de configuration et de fin du processus. Il encapsule le contenu NavEntry avec un SaveableStateProvider, ce qui permet aux appels rememberSaveable à l'intérieur du contenu NavEntry de fonctionner correctement.

Sauf si votre décorateur fournit un SaveableStateProvider, vous devez inclure SaveableStateHolderNavEntryDecorator comme premier décorateur dans votre liste de décorateurs fournis. Il est créé à l'aide de rememberSaveableStateHolderNavEntryDecorator.

Exemple :

// import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
NavDisplay(
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        remember { CustomNavEntryDecorator() }
    ),
    // ...
)
DecoratorSnippets.kt

Quand utiliser un décorateur ?

Utilisez un décorateur pour :

• Créez une dépendance pour chaque NavEntry dans une pile de retour. Par exemple, ViewModelStoreNavEntryDecorator crée un ViewModelStore pour chaque NavEntry.
• Définissez le champ d'application d'un objet sur plusieurs NavEntry. Par exemple, pour partager un ViewModel entre plusieurs entrées.
• Effectuez la même action pour plusieurs NavEntry. Par exemple, pour effectuer des opérations de journalisation, de débogage ou de traçage pour chaque entrée.
• Encapsulez les NavEntry avec la même fonction composable.
• Nettoyer l'état associé aux NavEntry. Par exemple, lorsqu'une entrée est supprimée de la pile "Retour", ViewModelStoreNavEntryDecorator efface son ViewModelStore associé.

N'utilisez pas de décorateur pour :

• Transmettez une dépendance à un seul NavEntry.
• Fournissez des dépendances dont le champ d'application est plus large que la pile "Retour".

Dans les deux cas, transmettez plutôt la dépendance directement lors de la création de NavEntry.

Pour obtenir d'autres exemples de code, consultez NavEntryDecorator.