Le composant Navigation fournit un moyen simple et générique d'accéder à une destination. Cette interface est compatible avec divers contextes et frameworks d'UI. Par exemple, vous pouvez utiliser le composant de navigation avec Compose, les vues, les fragments, les activités et même les frameworks d'UI personnalisés.
Ce guide explique comment utiliser le composant Navigation pour accéder à une destination dans des contextes différents.
Utiliser un NavController
Le type de clé que vous utilisez pour passer d'une destination à une autre est NavController
.
Pour en savoir plus sur la classe elle-même et sur la création d'une instance de celle-ci, consultez la section Create a navigation controller (Créer un contrôleur de navigation). Ce guide explique comment l'utiliser.
Accéder à une destination
Quel que soit le framework d'UI que vous utilisez, vous pouvez utiliser une unique fonction pour accéder à une destination : NavController.navigate()
.
De nombreuses surcharges sont disponibles pour navigate()
. La surcharge à choisir correspond à votre contexte précis. Par exemple, vous devez utiliser une surcharge lorsque vous accédez à un composable et une autre lorsque vous accédez à une vue.
Les sections suivantes décrivent certaines des principales surcharges navigate()
que vous pouvez
utiliser.
Accéder à un composable
Pour accéder à un composable, vous devez utiliser NavController.navigate<T>
.
Avec cette surcharge, navigate()
accepte un seul argument route
pour lequel vous
transmettre un type. Il sert de clé
vers une destination.
@Serializable
object FriendsList
navController.navigate(route = FriendsList)
Pour accéder à un composable dans le graphique de navigation, commencez par définir votre
NavGraph
de sorte que chaque destination corresponde à un type. Pour
Pour ce faire, utilisez la fonction composable()
.
Exposer des événements de vos composables
Lorsqu'une fonction composable doit accéder à un nouvel écran, vous ne devez pas lui transmettre de référence à NavController
pour pouvoir appeler directement navigate()
.
Conformément aux principes du flux de données unidirectionnel (UDF), le composable doit exposer un événement géré par NavController
.
En d'autres termes, votre composable doit comporter un paramètre de type () -> Unit
.
Lorsque vous ajoutez des destinations à votre NavHost
avec la fonction composable()
, transmettez votre à composable un appel à NavController.navigate()
.
Consultez la sous-section suivante pour un exemple.
Exemple
Comme le montrent les sections précédentes, observez ces points dans la l'extrait suivant:
- Chaque destination du graphique est créée à l'aide d'un itinéraire, objet ou classe sérialisable décrivant les données requises par ce vers votre destination.
- Le composable
MyAppNavHost
contient l'instanceNavController
. - Par conséquent, les appels à
navigate()
devraient y avoir lieu et non dans un composable inférieur, tel queProfileScreen
. ProfileScreen
contient un bouton qui redirige l'utilisateur versFriendsList
lorsqu'il clique dessus. Cependant, il n'appelle pasnavigate()
lui-même.- À la place, le bouton appelle une fonction exposée en tant que paramètre
onNavigateToFriends
. - Lorsque
MyAppNavHost
ajouteProfileScreen
au graphique de navigation, pouronNavigateToFriends
, elle transmet un lambda qui appellenavigate(route = FriendsList
). - Ainsi, lorsque l'utilisateur appuie sur le bouton
ProfileScreen
, il accède àFriendsListScreen
.
@Serializable
object Profile
@Serializable
object FriendsList
@Composable
fun MyAppNavHost(
modifier: Modifier = Modifier,
navController: NavHostController = rememberNavController(),
) {
NavHost(
modifier = modifier,
navController = navController,
startDestination = Profile
) {
composable<Profile> {
ProfileScreen(
onNavigateToFriends = { navController.navigate(route = FriendsList) },
/*...*/
)
}
composable<FriendsList> { FriendsListScreen(/*...*/) }
}
}
@Composable
fun ProfileScreen(
onNavigateToFriends: () -> Unit,
/*...*/
) {
/*...*/
Button(onClick = onNavigateToFriends) {
Text(text = "See friends list")
}
}
Naviguer à l'aide d'un ID entier
Pour accéder à une destination à l'aide d'un ID entier, appelez la surcharge navigate(int)
. Cette action va accepter l'ID de ressource d'une action ou d'une destination. L'extrait de code suivant montre comment utiliser cette surcharge pour accéder à ViewTransactionsFragment
:
Kotlin
viewTransactionsButton.setOnClickListener { view ->
view.findNavController().navigate(R.id.viewTransactionsAction)
}
Java
viewTransactionsButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
Navigation.findNavController(view).navigate(R.id.viewTransactionsAction);
}
});
Lorsque vous utilisez des ID, utilisez des actions lorsque cela est possible. Celles-ci fournissent des informations supplémentaires dans le graphe de navigation, indiquant visuellement comment vos destinations se connectent les unes aux autres.
Naviguer à l'aide de NavDeepLinkRequest
Pour accéder à une destination de lien profond implicite, utilisez la surcharge navigate(NavDeepLinkRequest)
. L'extrait de code suivant fournit une implémentation de cette méthode :
Kotlin
val request = NavDeepLinkRequest.Builder
.fromUri("android-app://androidx.navigation.app/profile".toUri())
.build()
findNavController().navigate(request)
Java
NavDeepLinkRequest request = NavDeepLinkRequest.Builder
.fromUri(Uri.parse("android-app://androidx.navigation.app/profile"))
.build()
NavHostFragment.findNavController(this).navigate(request)
Contrairement à la navigation à l'aide d'ID d'action ou de destination, vous pouvez accéder à n'importe quel lien profond de votre graphe, que la destination soit visible ou non. Vous pouvez accéder à une destination sur le graphe actuel ou sur un graphe complètement différent.
Actions et types MIME
En plus de Uri
, NavDeepLinkRequest
accepte également les liens profonds avec des actions et des types MIME. Pour ajouter une action à la requête, utilisez fromAction()
ou setAction()
. Pour ajouter un type MIME à une requête, utilisez fromMimeType()
ou setMimeType()
.
Pour qu'une propriété NavDeepLinkRequest
soit correctement associée à une destination implicite de lien profond, l'URI, l'action et le type MIME doivent tous correspondre à l'élément NavDeepLink
dans la destination. Les URI doivent correspondre au format, les actions doivent être une correspondance exacte et les types MIME doivent être liés. Par exemple, image/jpg
correspond à image/\*
.
Autres contextes
Ce document explique comment utiliser NavController.navigate()
dans les cas d'utilisation les plus courants. Cependant, la fonction comporte une plage de surcharges que vous pouvez utiliser dans différents contextes et en tandem avec n'importe quel framework d'UI. Pour en savoir plus sur ces surcharges, consultez la documentation de référence.
Complément d'informations
Pour en savoir plus, consultez les pages suivantes :
- Créer un contrôleur de navigation
- Navigation et pile "Retour"
- Naviguer avec des options
- Sûreté du typage dans le DSL Kotlin et Navigation Compose