Premiers pas avec le composant Navigation

Configurer votre environnement

Pour inclure la prise en charge du composant Navigation dans votre projet, ajoutez les dépendances suivantes au fichier build.gradle de votre application :

dependencies {
  def nav_version = "2.5.3"

  // Java language implementation
  implementation "androidx.navigation:navigation-fragment:$nav_version"
  implementation "androidx.navigation:navigation-ui:$nav_version"

  // Kotlin
  implementation "androidx.navigation:navigation-fragment-ktx:$nav_version"
  implementation "androidx.navigation:navigation-ui-ktx:$nav_version"

  // Feature module Support
  implementation "androidx.navigation:navigation-dynamic-features-fragment:$nav_version"

  // Testing Navigation
  androidTestImplementation "androidx.navigation:navigation-testing:$nav_version"

  // Jetpack Compose Integration
  implementation "androidx.navigation:navigation-compose:$nav_version"
}

dependencies {
  val nav_version = "2.5.3"

  // Java language implementation
  implementation("androidx.navigation:navigation-fragment:$nav_version")
  implementation("androidx.navigation:navigation-ui:$nav_version")

  // Kotlin
  implementation("androidx.navigation:navigation-fragment-ktx:$nav_version")
  implementation("androidx.navigation:navigation-ui-ktx:$nav_version")

  // Feature module Support
  implementation("androidx.navigation:navigation-dynamic-features-fragment:$nav_version")

  // Testing Navigation
  androidTestImplementation("androidx.navigation:navigation-testing:$nav_version")

  // Jetpack Compose Integration
  implementation("androidx.navigation:navigation-compose:$nav_version")
}

Pour plus d'informations sur l'ajout de composants d'architecture à votre projet, consultez le guide Ajouter des composants à votre projet.

Créer un graphique de navigation

La navigation a lieu entre les destinations de votre application, c'est-à-dire les emplacements de votre application auxquels les utilisateurs peuvent accéder. Ces destinations sont connectées via des actions.

Un graphique de navigation est un fichier de ressources contenant toutes vos destinations et actions. Le graphique représente tous les chemins de navigation de votre application.

La figure 1 est une représentation visuelle d'un graphique de navigation pour un exemple d'application contenant six destinations connectées par cinq actions. Chaque destination est représentée par une vignette d'aperçu, et les actions de connexion sont représentées par des flèches qui montrent comment les utilisateurs peuvent passer d'une destination à une autre.

1. Les destinations correspondent aux différentes zones de contenu de votre application.
2. Les actions sont des connexions logiques entre vos destinations et représentent les chemins que les utilisateurs peuvent emprunter.

Pour ajouter un graphique de navigation à votre projet, procédez comme suit :

1. Dans la fenêtre du projet, faites un clic droit sur le répertoire res et sélectionnez New > Android Resource File (Nouveau > Fichier de ressources Android). La boîte de dialogue New Resource File (Nouveau fichier de ressources) s'affiche.
2. Saisissez un nom dans le champ File name (Nom du fichier), par exemple "nav_graph".
3. Sélectionnez Navigation dans la liste déroulante Resource type (Type de ressource), puis cliquez sur OK.

Lorsque vous ajoutez votre premier graphique de navigation, Android Studio crée un répertoire de ressources navigation dans le répertoire res. Ce répertoire contient votre fichier de ressources de graphique de navigation (nav_graph.xml, par exemple).

Éditeur de navigation

Après avoir ajouté un graphique, Android Studio l'ouvre dans l'éditeur de navigation. Dans l'éditeur de navigation, vous pouvez modifier visuellement les graphiques de navigation ou modifier directement le code XML sous-jacent.

1. Panneau "Destinations" : répertorie votre hôte de navigation et toutes les destinations actuellement dans l'éditeur de graphique.
2. Éditeur de graphique : contient une représentation visuelle de votre graphique de navigation. Vous pouvez basculer entre la vue Design (Conception) et la représentation XML sous-jacente dans la vue Text (Texte).
3. Attributes (Attributs) : affiche les attributs de l'élément actuellement sélectionné dans le graphique de navigation.

Cliquez sur l'onglet Text (Texte) pour afficher le fichier XML correspondant, qui doit ressembler à l'extrait de code suivant :

<?xml version="1.0" encoding="utf-8"?>
<navigation xmlns:android="http://schemas.android.com/apk/res/android"
            xmlns:app="http://schemas.android.com/apk/res-auto"
            android:id="@+id/nav_graph">

</navigation>

L'élément <navigation> est l'élément racine d'un graphique de navigation. Lorsque vous ajoutez des destinations et associez des actions à votre graphique, les éléments <destination> et <action> correspondants peuvent s'afficher ici en tant qu'éléments enfants. Si vous disposez de graphiques imbriqués, ils apparaissent en tant qu'éléments enfants <navigation>.

Ajouter un NavHost à une activité

L'un des principaux composants du composant Navigation est l'hôte de navigation. L'hôte de navigation est un conteneur vide dans lequel les destinations sont échangées lorsqu'un utilisateur parcourt votre application.

Un hôte de navigation doit dériver de NavHost. L'implémentation NavHost par défaut du composant Navigation, NavHostFragment, gère l'échange de destinations de fragments.

Ajouter un NavHostFragment via XML

L'exemple XML ci-dessous présente un élément NavHostFragment faisant partie de l'activité principale d'une application :

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <androidx.appcompat.widget.Toolbar
        .../>

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="0dp"
        android:layout_height="0dp"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintBottom_toBottomOf="parent"

        app:defaultNavHost="true"
        app:navGraph="@navigation/nav_graph" />

    <com.google.android.material.bottomnavigation.BottomNavigationView
        .../>

</androidx.constraintlayout.widget.ConstraintLayout>

Remarque :

• L'attribut android:name contient le nom de classe de votre implémentation NavHost.
• L'attribut app:navGraph associe NavHostFragment à un graphique de navigation. Le graphique de navigation spécifie toutes les destinations de ce NavHostFragment auxquelles les utilisateurs peuvent accéder.
• L'attribut app:defaultNavHost="true" garantit que votre NavHostFragment intercepte le bouton "Retour" du système. Notez qu'un seul élément NavHost peut être utilisé par défaut. Si plusieurs hôtes se trouvent dans la même mise en page (par exemple, deux volets), veillez à ne spécifier qu'un seul élément NavHost par défaut.

Vous pouvez également utiliser l'éditeur de mise en page pour ajouter un élément NavHostFragment à une activité en procédant comme suit :

1. Dans la liste des fichiers de projet, double-cliquez sur le fichier XML de mise en page de votre activité pour l'ouvrir dans l'éditeur de mise en page.
2. Dans le volet Palette, choisissez la catégorie Containers (Conteneurs) ou recherchez "NavHostFragment".
3. Faites glisser la vue NavHostFragment vers votre activité.
4. Dans la boîte de dialogue Navigation Graphs (Graphiques de navigation) qui s'affiche, sélectionnez le graphique de navigation correspondant à ce NavHostFragment, puis cliquez sur OK.

Ajouter des destinations au graphique de navigation

Vous pouvez créer une destination à partir d'un fragment ou d'une activité existants. Vous pouvez également utiliser l'éditeur de navigation pour créer une destination ou un espace réservé à remplacer ultérieurement par un fragment ou une activité.

Dans cet exemple, nous allons créer une destination. Pour ajouter une destination à l'aide de l'éditeur de navigation, procédez comme suit :

1. Dans l'éditeur de navigation, cliquez sur l'icône New Destination  (Nouvelle destination), puis sur Create new destination (Créer une destination).
2. Dans la boîte de dialogue Nouveau composant Android qui s'affiche, créez votre fragment. Pour en savoir plus sur les fragments, consultez les documents concernant les fragments.

De retour dans l'éditeur de navigation, notez qu'Android Studio a ajouté cette destination au graphique.

La figure 3 est un exemple de destination et d'espace réservé.

Pour découvrir d'autres façons d'ajouter des destinations à votre graphique de navigation, consultez le guide Créer des destinations.

Anatomie d'une destination

Cliquez sur une destination pour la sélectionner et notez les attributs suivants dans le panneau Attributes (Attributs) :

• Le champ Type indique si la destination est implémentée en tant que fragment, activité ou autre classe personnalisée dans votre code source.
• Le champ Label (Libellé) contient le nom de la destination lisible par l'utilisateur. Il peut s'afficher dans l'interface utilisateur, par exemple si vous connectez le NavGraph à Toolbar avec setupWithNavController(). C'est pourquoi nous vous recommandons d'utiliser des chaînes de ressources pour cette valeur.
• Le champ ID contient l'ID de la destination qui est utilisé pour faire référence à la destination dans le code.
• La liste déroulante Class (Classe) affiche le nom de la classe associée à la destination. Vous pouvez cliquer sur ce menu déroulant pour remplacer la classe associée par un autre type de destination.

Cliquez sur l'onglet Text (Texte) pour afficher la vue XML de votre graphique de navigation. Le fichier XML contient les mêmes attributs id, name, label et layout pour la destination, comme indiqué ci-dessous :

<?xml version="1.0" encoding="utf-8"?>
<navigation xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:android="http://schemas.android.com/apk/res/android"
    app:startDestination="@id/blankFragment">
    <fragment
        android:id="@+id/blankFragment"
        android:name="com.example.cashdog.cashdog.BlankFragment"
        android:label="@string/label_blank"
        tools:layout="@layout/fragment_blank" />
</navigation>

Désigner un écran comme destination de départ

La destination de départ est le premier écran que les utilisateurs voient lorsqu'ils ouvrent votre application. C'est également le dernier écran que les utilisateurs voient lorsqu'ils quittent l'application. L'éditeur de navigation utilise une icône représentant une maison pour indiquer la destination de départ.

Une fois que vous avez défini toutes vos destinations, vous pouvez choisir une destination de départ en procédant comme suit :

1. Dans l'onglet Design (Conception), cliquez sur la destination pour la mettre en évidence.

2. Cliquez sur le bouton Assign start destination  (Attribuer une destination de départ). Vous pouvez également faire un clic droit sur la destination, puis cliquer sur Set as Start Destination (Définir comme destination de départ).

Connecter des destinations

Une action est une connexion logique entre des destinations. Les actions sont représentées par des flèches dans le graphique de navigation. Les actions connectent généralement une destination à une autre, mais vous pouvez également créer des actions globales qui vous redirigent vers une destination spécifique où que vous soyez dans votre application.

Les actions vous permettent de représenter les différents chemins que les utilisateurs peuvent emprunter dans votre application. Notez que pour accéder aux destinations, vous devez toujours écrire le code permettant d'effectuer la navigation. Ce point est abordé plus loin dans la section Accéder à une destination.

Vous pouvez utiliser l'éditeur de navigation pour connecter deux destinations en procédant comme suit :

1. Dans l'onglet Design (Conception), pointez sur le côté droit de la destination à laquelle vous souhaitez que les utilisateurs accèdent. Un cercle apparaît sur le côté droit de la destination, comme illustré dans la figure 4.

   

2. Faites glisser votre curseur vers la destination à laquelle vous souhaitez que les utilisateurs accèdent, puis relâchez. La ligne obtenue entre les deux destinations représente une action, comme illustré dans la figure 5.

   

3. Cliquez sur la flèche pour mettre l'action en surbrillance. Les attributs suivants apparaissent dans le panneau Attributes (Attributs) :

   • Le champ Type contient "Action".
   • Le champ ID contient l'ID de l'action.
   • Le champ Destination contient l'ID du fragment ou de l'activité de destination.

4. Cliquez sur l'onglet Text (Texte) pour passer à la vue XML. Un élément d'action est maintenant ajouté à la destination source. L'action comporte un ID et un attribut de destination contenant l'ID de la destination suivante, comme illustré dans l'exemple ci-dessous :

   <?xml version="1.0" encoding="utf-8"?>
   <navigation xmlns:app="http://schemas.android.com/apk/res-auto"
       xmlns:tools="http://schemas.android.com/tools"
       xmlns:android="http://schemas.android.com/apk/res/android"
       app:startDestination="@id/blankFragment">
       <fragment
           android:id="@+id/blankFragment"
           android:name="com.example.cashdog.cashdog.BlankFragment"
           android:label="@string/label_blank"
           tools:layout="@layout/fragment_blank" >
           <action
               android:id="@+id/action_blankFragment_to_blankFragment2"
               app:destination="@id/blankFragment2" />
       </fragment>
       <fragment
           android:id="@+id/blankFragment2"
           android:name="com.example.cashdog.cashdog.BlankFragment2"
           android:label="@string/label_blank_2"
           tools:layout="@layout/fragment_blank_fragment2" />
   </navigation>
   

Dans votre graphique de navigation, les actions sont représentées par des éléments <action>. Au minimum, une action contient son propre ID et celui de la destination vers laquelle l'utilisateur doit être redirigé.

Accéder à une destination

La navigation vers une destination est effectuée à l'aide d'un objet NavController, qui gère la navigation dans l'application via un NavHost. Chaque NavHost a son propre NavController correspondant. Vous pouvez récupérer un NavController à l'aide de l'une des méthodes suivantes :

Kotlin :

• Fragment.findNavController()
• View.findNavController()
• Activity.findNavController(viewId: Int)

Java :

• NavHostFragment.findNavController(Fragment)
• Navigation.findNavController(Activity, @IdRes int viewId)
• Navigation.findNavController(View)

Si vous créez le NavHostFragment à l'aide de FragmentContainerView ou si vous ajoutez manuellement le NavHostFragment à votre activité via un FragmentTransaction, la tentative de récupération de NavController dans onCreate() pour une activité via Navigation.findNavController(Activity, @IdRes int) échouera. Vous devez plutôt récupérer NavController directement à partir de NavHostFragment.

val navHostFragment =
        supportFragmentManager.findFragmentById(R.id.nav_host_fragment) as NavHostFragment
val navController = navHostFragment.navController

NavHostFragment navHostFragment =
        (NavHostFragment) getSupportFragmentManager().findFragmentById(R.id.nav_host_fragment);
NavController navController = navHostFragment.getNavController();

Assurer la sécurité du type à l'aide de Safe Args

Pour naviguer entre les destinations, nous vous recommandons d'utiliser le plug-in Gradle Safe Args. Ce plug-in génère des classes d'objets et de compilateurs simples qui permettent une navigation sécurisée par type et un transfert d'argument entre les destinations.

Pour ajouter Safe Args à votre projet, incluez le classpath suivant dans votre fichier build.gradle de premier niveau :

buildscript {
    repositories {
        google()
    }
    dependencies {
        def nav_version = "2.5.3"
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
    }
}

buildscript {
    repositories {
        google()
    }
    dependencies {
        val nav_version = "2.5.3"
        classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version")
    }
}

Vous devez également appliquer l'un des deux plug-ins disponibles.

Pour générer un code en langage Java adapté aux modules en Java ou mixant du Java et du Kotlin, ajoutez la ligne suivante au fichier build.gradle de votre application ou module :

plugins {
  id 'androidx.navigation.safeargs'
}

plugins {
    id("androidx.navigation.safeargs")
}

Sinon, pour générer un code Kotlin adapté aux modules exclusivement en Kotlin, ajoutez la ligne suivante :

plugins {
  id 'androidx.navigation.safeargs.kotlin'
}

plugins {
    id("androidx.navigation.safeargs.kotlin")
}

android.useAndroidX=true doit figurer dans votre fichier gradle.properties, tel qu'indiqué sur la page Migrer vers AndroidX.

Une fois que vous avez activé Safe Args, le plug-in génère du code contenant des classes et des méthodes pour chaque action que vous avez définie. Pour chaque action, Safe Args génère également une classe pour chaque destination d'origine, qui correspond à la destination d'où provient l'action. Le nom de classe généré est une combinaison du nom de la classe de destination d'origine et du mot "Directions". Par exemple, si la destination est nommée SpecifyAmountFragment, la classe générée est nommée SpecifyAmountFragmentDirections. La classe générée contient une méthode statique pour chaque action définie dans la destination d'origine. Cette méthode utilise tous les paramètres d'action définis comme arguments et renvoie un objet NavDirections que vous pouvez transmettre à navigate().

Par exemple, supposons que nous ayons un graphique de navigation avec une seule action qui connecte la destination d'origine, SpecifyAmountFragment, à une destination de réception, ConfirmationFragment.

Safe Args génère une classe SpecifyAmountFragmentDirections avec une seule méthode, actionSpecifyAmountFragmentToConfirmationFragment() qui renvoie un objet NavDirections. Cet objet NavDirections renvoyé peut ensuite être transmis directement à navigate(), comme illustré dans l'exemple suivant :

override fun onClick(view: View) {
    val action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment()
    view.findNavController().navigate(action)
}

@Override
public void onClick(View view) {
    NavDirections action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment();
    Navigation.findNavController(view).navigate(action);
}

Pour en savoir plus sur la transmission de données entre des destinations avec Safe Args, consultez la section Utiliser Safe Args pour transmettre des données en toute sécurité.

En savoir plus

• Présentation de la navigation
• Créer des destinations
• Accéder à une destination
• Mettre à jour les composants de l'UI avec NavigationUI
• Transmettre des données entre les destinations
• Actions générales
• Destinations conditionnelles
• Types de destinations personnalisés
• Android Jetpack : gérer la navigation dans l'interface utilisateur avec Navigation Controller (Google I/O 2018)
• Migrer un projet existant vers le composant d'architecture Navigation
• Atelier de programmation sur le composant Navigation

Si vous rencontrez des problèmes avec Navigation, veuillez nous envoyer vos commentaires via l'un des canaux suivants :

• Signaler un bug dans l'éditeur Navigation
• Signaler un bug dans la bibliothèque Navigation
• Signaler un problème sur StackOverflow

Pour savoir comment fournir les informations les plus utiles dans les rapports de bug, cliquez sur les liens suivants :

• Signaler des bugs (plate-forme Android)
• Signaler un bug (Android Studio)