Le composant de navigation utilise un graphique de navigation pour gérer la navigation dans votre appli. Le graphique de navigation est une structure de données qui contient chaque destination de votre appli ainsi que les connexions qui s'établissent entre elles.
Types de destinations
Il existe trois principaux types de destinations : destination hébergée, destination de boîte de dialogue et destination d'activité. Le tableau ci-dessous décrit ces trois types de destinations ainsi que leurs objectifs.
Type |
Description |
Cas d'utilisation |
---|---|---|
Destination hébergée |
Occupe l'intégralité de l'hôte de navigation. Autrement dit, la taille d'une destination hébergée est identique à celle de l'hôte de navigation, et les destinations précédentes ne sont pas visibles. |
Écran principal et page d'informations |
Destination de boîte de dialogue |
Présente les composants d'interface utilisateur superposés. Cette interface utilisateur n'est pas liée à l'emplacement de l'hôte de navigation ni à sa taille. Les destinations précédentes sont visibles sous la destination. |
Alertes, sélections, formulaires. |
Destination d'activité |
Représente des pages ou des fonctionnalités uniques au sein de l'appli. |
Sert de point de sortie au graphique de navigation qui lance une nouvelle activité Android gérée indépendamment du composant Navigation. Dans Modern Android Development, une appli se compose d'une seule activité. Lorsqu'elles interagissent avec des activités tierces ou dans le cadre du processus de migration, les destinations des activités sont ainsi mieux utilisées. |
Ce document contient des exemples de destinations hébergées, qui sont les destinations les plus courantes et les plus fondamentales. Pour en savoir plus sur les autres destinations, consultez les guides suivants :
Frameworks
Bien que le même workflow général s'applique dans tous les cas, la manière exacte de créer un hôte et un graphique de navigation dépend du framework d'interface utilisateur que vous utilisez.
- Compose : utilisez le composable
NavHost
. Ajoutez-y unNavGraph
à l'aide de la méthode DSL Kotlin. Il existe deux manières de créer le graphique :- Dans NavHost : construisez le graphique de navigation directement lors de l'ajout de
NavHost
. - Par programmation : utilisez la méthode
NavController.createGraph()
pour créer unNavGraph
et le transmettre directement àNavHost
.
- Dans NavHost : construisez le graphique de navigation directement lors de l'ajout de
- Fragments:lorsque vous utilisez des fragments avec le framework de l'interface utilisateur Vues, utilisez un
NavHostFragment
en tant qu'hôte. Il existe plusieurs façons de créer une navigation graphique: <ph type="x-smartling-placeholder">- </ph>
- Par programmation:utilisez le DSL Kotlin pour créer un
NavGraph
et l'appliquer directement sur leNavHostFragment
.- La fonction
createGraph()
utilisée avec le DSL Kotlin pour les deux les fragments et Compose est identique.
- La fonction
- XML : écrivez votre hôte de navigation ainsi que votre graphique de navigation directement en XML.
- Éditeur Android Studio : utilisez l'éditeur IUG dans Android Studio pour créer et ajuster votre graphique en tant que fichier de ressources XML.
- Par programmation:utilisez le DSL Kotlin pour créer un
Compose
Dans Compose, utilisez un objet ou une classe sérialisable pour définir une route. Un itinéraire
décrit comment se rendre à une destination et contient toutes les informations
la destination de l'annonce. Une fois que vous avez défini vos routes, utilisez le NavHost
pour créer votre graphique de navigation. Prenons l'exemple suivant :
@Serializable
object Profile
@Serializable
object FriendsList
val navController = rememberNavController()
NavHost(navController = navController, startDestination = Profile) {
composable<Profile> { ProfileScreen( /* ... */ ) }
composable<FriendsList> { FriendsListScreen( /* ... */ ) }
// Add more destinations similarly.
}
- Un objet sérialisable représente chacune des deux routes,
Profile
etFriendsList
- L'appel du composable
NavHost
transmet unNavController
et une route pour la destination de départ. - Le lambda transmis à
NavHost
appelle finalementNavController.createGraph()
et renvoie unNavGraph
. - Chaque route est fournie en tant qu'argument de type pour
NavGraphBuilder.composable<T>()
, qui ajoute la destination auNavGraph
. - Le lambda transmis à
composable
est ce queNavHost
affiche pour cela. vers votre destination.
Comprendre le lambda
Pour mieux comprendre le lambda qui crée le NavGraph
, n'oubliez pas que pour créer le même graphique que dans l'extrait précédent, vous pouvez créer le NavGraph
séparément à l'aide de NavController.createGraph()
et le transmettre directement à NavHost
:
val navGraph by remember(navController) {
navController.createGraph(startDestination = Profile)) {
composable<Profile> { ProfileScreen( /* ... */ ) }
composable<FriendsList> { FriendsListScreen( /* ... */ ) }
}
}
NavHost(navController, navGraph)
Transmettre des arguments
Si vous devez transmettre des données à une destination, définissez l'itinéraire avec une classe qui
comporte des paramètres. Par exemple, la route Profile
est une classe de données avec un name
.
.
@Serializable
data class Profile(val name: String)
Chaque fois que vous devez transmettre des arguments à cette destination, vous créez une instance de votre classe d'itinéraire, en transmettant les arguments au constructeur de la classe.
Pour les arguments facultatifs, créez des champs pouvant avoir une valeur nulle avec une valeur par défaut.
@Serializable
data class Profile(val nickname: String? = null)
Obtenir une instance de route
Vous pouvez obtenir l'instance de route avec NavBackStackEntry.toRoute()
ou
SavedStateHandle.toRoute()
Lorsque vous créez une destination à l'aide de
composable()
, NavBackStackEntry
est disponible en tant que paramètre.
@Serializable
data class Profile(val name: String)
val navController = rememberNavController()
NavHost(navController = navController, startDestination = Profile(name="John Smith")) {
composable<Profile> { backStackEntry ->
val profile: Profile = backStackEntry.toRoute()
ProfileScreen(name = profile.name) }
}
Notez les points suivants dans cet extrait:
- La route
Profile
spécifie la destination de départ dans la navigation graphique, avec"John Smith"
comme argument pourname
. - La destination elle-même est le bloc
composable<Profile>{}
. - Le composable
ProfileScreen
prend comme valeurprofile.name
name
. - Par conséquent, la valeur
"John Smith"
est transmise àProfileScreen
.
Exemple minimal
Exemple complet d'utilisation conjointe de NavController
et NavHost
:
@Serializable
data class Profile(val name: String)
@Serializable
object FriendsList
// Define the ProfileScreen composable.
@Composable
fun ProfileScreen(
profile: Profile
onNavigateToFriendsList: () -> Unit,
) {
Text("Profile for ${profile.name}")
Button(onClick = { onNavigateToFriendsList() }) {
Text("Go to Friends List")
}
}
// Define the FriendsListScreen composable.
@Composable
fun FriendsListScreen(onNavigateToProfile: () -> Unit) {
Text("Friends List")
Button(onClick = { onNavigateToProfile() }) {
Text("Go to Profile")
}
}
// Define the MyApp composable, including the `NavController` and `NavHost`.
@Composable
fun MyApp() {
val navController = rememberNavController()
NavHost(navController, startDestination = Profile(name = "John Smith")) {
composable<Profile> { backStackEntry ->
val profile: Profile = backStackEntry.toRoute()
ProfileScreen(
profile = profile,
onNavigateToFriendsList = {
navController.navigate(route = FriendsList)
}
)
}
composable<FriendsList> {
FriendsListScreen(
onNavigateToProfile = {
navController.navigate(
route = Profile(name = "Aisha Devi")
)
}
)
}
}
}
Comme le montre l'extrait, plutôt que de transmettre le NavController
à vos composables, exposez un événement à NavHost
. Autrement dit, vos composables doivent comporter un paramètre de type () -> Unit
pour lequel NavHost
transmet un lambda qui appelle NavController.navigate()
.
Fragments
Comme indiqué dans les sections précédentes, lorsque vous utilisez des fragments, vous avez la possibilité de créer un graphique de navigation par programmation à l'aide du DSL Kotlin, du XML ou de l'éditeur Android Studio.
Les sections suivantes reviennent plus en détail sur ces différentes approches.
Par programmation
Le DSL Kotlin permet de créer un graphique de navigation avec des fragments de façon programmatique. À bien des égards, cette méthode est plus pratique et plus moderne que le recours à un fichier de ressources XML.
Prenons l'exemple suivant, qui implémente un graphique de navigation sur deux écrans.
Vous devez d'abord créer le NavHostFragment
, qui ne doit pas inclure
Un élément app:navGraph
:
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent">
<androidx.fragment.app.FragmentContainerView
android:id="@+id/nav_host_fragment"
android:name="androidx.navigation.fragment.NavHostFragment"
android:layout_width="match_parent"
android:layout_height="match_parent" />
</FrameLayout>
Transmettez ensuite l'id
du NavHostFragment
à NavController.findNavController
. Cela associe NavController à
le NavHostFragment
.
Par la suite, l'appel à NavController.createGraph()
associe le graphique à
NavController
et, par conséquent, à NavHostFragment
:
@Serializable
data class Profile(val name: String)
@Serializable
object FriendsList
// Retrieve the NavController.
val navController = findNavController(R.id.nav_host_fragment)
// Add the graph to the NavController with `createGraph()`.
navController.graph = navController.createGraph(
startDestination = Profile(name = "John Smith")
) {
// Associate each destination with one of the route constants.
fragment<ProfileFragment, Profile> {
label = "Profile"
}
fragment<FriendsListFragment, FriendsList>() {
label = "Friends List"
}
// Add other fragment destinations similarly.
}
Cette manière d'utiliser le DSL est très semblable au workflow décrit dans la section précédente sur Compose. Par exemple, ici et là, la fonction NavController.createGraph()
génère le NavGraph
. De même, tandis que NavGraphBuilder.composable()
ajoute des destinations de composable au graphique, NavGraphBuilder.fragment()
ajoute une destination de fragment.
Pour en savoir plus sur l'utilisation du DSL Kotlin, consultez la section Créer un graphe par programmation à l'aide du langage DSL Kotlin.
XML
Vous pouvez rédiger vous-même le code XML directement. L'exemple suivant est le même que celui présenté à la section précédente (sur deux écrans).
Commencez par créer un NavHostFragment
. Ce dernier servira d'hôte de navigation et contiendra le graphique de navigation.
Implémentation minimale d'un NavHostFragment
:
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent">
<androidx.fragment.app.FragmentContainerView
android:id="@+id/nav_host_fragment"
android:name="androidx.navigation.fragment.NavHostFragment"
android:layout_width="match_parent"
android:layout_height="match_parent"
app:navGraph="@navigation/nav_graph" />
</FrameLayout>
Le NavHostFragment
contient l'attribut app:navGraph
. Utiliser cet attribut
pour connecter votre graphique de navigation à l'hôte de navigation. Voici un exemple d'implémentation du graphique :
<navigation xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:id="@+id/nav_graph"
app:startDestination="@id/profile">
<fragment
android:id="@+id/profile"
android:name="com.example.ProfileFragment"
android:label="Profile">
<!-- Action to navigate from Profile to Friends List. -->
<action
android:id="@+id/action_profile_to_friendslist"
app:destination="@id/friendslist" />
</fragment>
<fragment
android:id="@+id/friendslist"
android:name="com.example.FriendsListFragment"
android:label="Friends List" />
<!-- Add other fragment destinations similarly. -->
</navigation>
Les actions vous permettent de définir les connexions entre les différentes destinations. Dans cet exemple, le fragment profile
contient une action qui permet d'accéder à friendslist
. Pour en savoir plus, consultez la section Utiliser les actions de navigation et les fragments.
Éditeur
Vous pouvez gérer le graphique de navigation de votre appli à l'aide de l'éditeur de navigation d'Android Studio. Il s'agit essentiellement d'une IUG que vous pouvez utiliser pour créer et modifier votre fichier XML NavigationFragment
, comme indiqué dans la section précédente.
Pour en savoir plus, consultez la section Éditeur de navigation.
Graphiques imbriqués
Vous pouvez également utiliser des graphiques imbriqués. Cela implique l'utilisation d'un graphique comme destination de navigation. Pour en savoir plus, consultez la section Graphiques imbriqués.
Complément d'informations
Pour plus de concepts de base concernant la navigation, consultez les guides suivants :
- Présentation : veillez à lire la présentation générale du composant Navigation.
- Destinations d'activité : exemples d'implémentation de destinations qui redirigent l'utilisateur vers des activités.
- Destinations de boîte de dialogue : exemples illustrant la façon de créer des destinations qui redirigent l'utilisateur vers une boîte de dialogue.
- Accéder à une destination : guide détaillé expliquant comment passer d'une destination à une autre.
- Graphiques imbriqués:guide détaillé sur l'imbrication d'une interface de navigation graphique dans un autre.