Navigation avec Compose

Le composant Navigation est compatible avec les applications Jetpack Compose. Vous pouvez naviguer entre les composables tout en tirant parti de l'infrastructure et des fonctionnalités du composant Navigation.

Configurer

Pour prendre en charge Compose, utilisez la dépendance suivante dans le fichier build.gradle de votre module d'application:

Groovy

dependencies {
    def nav_version = "2.7.7"

    implementation "androidx.navigation:navigation-compose:$nav_version"
}

Kotlin

dependencies {
    val nav_version = "2.7.7"

    implementation("androidx.navigation:navigation-compose:$nav_version")
}

Premiers pas

Lorsque vous implémentez la navigation dans une application, mettez en œuvre un hôte, un graphique et un contrôleur de navigation. Pour en savoir plus, consultez la présentation de Navigation.

Pour en savoir plus sur la création d'un NavController dans Compose, consultez la section Compose de la section Créer un contrôleur de navigation.

Créer un NavHost

Pour en savoir plus sur la création d'un NavHost dans Compose, consultez la section Compose de la page Concevoir votre graphique de navigation.

Pour en savoir plus sur la navigation vers un composable, consultez la section Accéder à une destination dans la documentation sur l'architecture.

Navigation Compose permet également de transmettre des arguments entre des destinations de composables. Pour ce faire, vous devez ajouter des espaces réservés aux arguments sur votre itinéraire, comme lorsque vous ajoutez des arguments à un lien profond en utilisant la bibliothèque de navigation de base :

NavHost(startDestination = "profile/{userId}") {
    ...
    composable("profile/{userId}") {...}
}

Par défaut, tous les arguments sont analysés sous forme de chaînes. Le paramètre arguments de composable() accepte une liste d'objets NamedNavArgument. Vous pouvez créer rapidement un NamedNavArgument à l'aide de la méthode navArgument(), puis spécifier son type exact:

NavHost(startDestination = "profile/{userId}") {
    ...
    composable(
        "profile/{userId}",
        arguments = listOf(navArgument("userId") { type = NavType.StringType })
    ) {...}
}

Vous devez extraire les arguments du NavBackStackEntry disponible dans le lambda de la fonction composable().

composable("profile/{userId}") { backStackEntry ->
    Profile(navController, backStackEntry.arguments?.getString("userId"))
}

Pour transmettre l'argument à la destination, vous devez l'ajouter à l'itinéraire lorsque vous effectuez l'appel navigate :

navController.navigate("profile/user1234")

Pour obtenir la liste des types compatibles, consultez la section Transmettre des données entre les destinations.

Récupérer des données complexes lors de la navigation

Lorsque vous effectuez des actions de navigation, nous vous recommandons vivement de ne pas transmettre d'objets de données complexes, mais plutôt de transmettre le strict minimum (comme un identifiant unique ou une autre forme d'ID) sous la forme d'arguments.

// Pass only the user ID when navigating to a new destination as argument
navController.navigate("profile/user1234")

Les objets complexes doivent être stockés sous forme de données dans une source unique de référence, telle que la couche de données. Une fois arrivé à destination après votre navigation, vous pouvez charger les informations requises à partir de la référence unique en utilisant l'ID transmis. Pour récupérer les arguments de votre ViewModel responsables de l'accès à la couche de données, utilisez le SavedStateHandle de l'ViewModel:

class UserViewModel(
    savedStateHandle: SavedStateHandle,
    private val userInfoRepository: UserInfoRepository
) : ViewModel() {

    private val userId: String = checkNotNull(savedStateHandle["userId"])

    // Fetch the relevant user information from the data layer,
    // ie. userInfoRepository, based on the passed userId argument
    private val userInfo: Flow<UserInfo> = userInfoRepository.getUserInfo(userId)

// …

}

Cette approche permet de conserver les données lors des modifications de configuration et d'éviter les incohérences lors de la mise à jour ou de la mutation d'un objet.

Pour découvrir pourquoi vous devez éviter de transmettre des données complexes en tant qu'arguments, et pour obtenir la liste des types d'arguments compatibles, consultez la page Transmettre des données entre les destinations.

Ajouter des arguments facultatifs

Navigation Compose accepte également les arguments de navigation facultatifs. Les arguments facultatifs présentent deux différences par rapport aux arguments obligatoires :

  • Ils doivent être inclus à l'aide de la syntaxe des paramètres de requête ("?argName={argName}").
  • Ils doivent avoir une valeur defaultValue ou nullable = true (qui définit implicitement la valeur par défaut sur null).

Cela signifie que tous les arguments facultatifs doivent être explicitement ajoutés à la fonction composable() sous forme de liste :

composable(
    "profile?userId={userId}",
    arguments = listOf(navArgument("userId") { defaultValue = "user1234" })
) { backStackEntry ->
    Profile(navController, backStackEntry.arguments?.getString("userId"))
}

Désormais, même si aucun argument n'est transmis à la destination, le champ defaultValue ("user1234") est utilisé à la place.

Avec la structure de traitement des arguments via les itinéraires, vos composables restent entièrement indépendants de la navigation. Vous pouvez donc les tester plus facilement.

Navigation Compose accepte également les liens profonds implicites qui peuvent également être définis dans la fonction composable(). Son paramètre deepLinks accepte une liste d'objets NavDeepLink, qui peuvent être créés rapidement à l'aide de la méthode navDeepLink():

val uri = "https://www.example.com"

composable(
    "profile?id={id}",
    deepLinks = listOf(navDeepLink { uriPattern = "$uri/{id}" })
) { backStackEntry ->
    Profile(navController, backStackEntry.arguments?.getString("id"))
}

Ces liens profonds vous permettent d'associer une URL, une action ou un type MIME spécifique à un composable. Par défaut, ces liens profonds ne sont pas exposés à des applications externes. Pour rendre ces liens profonds disponibles en externe, vous devez ajouter les éléments <intent-filter> appropriés au fichier manifest.xml de votre application. Pour activer le lien profond dans l'exemple précédent, vous devez ajouter le code suivant dans l'élément <activity> du fichier manifeste:

<activity …>
  <intent-filter>
    ...
    <data android:scheme="https" android:host="www.example.com" />
  </intent-filter>
</activity>

La navigation crée automatiquement un lien profond dans ce composable lorsque le lien profond est déclenché par une autre application.

Ces mêmes liens profonds peuvent également être utilisés pour créer un PendingIntent avec le lien profond approprié à partir d'un composable :

val id = "exampleId"
val context = LocalContext.current
val deepLinkIntent = Intent(
    Intent.ACTION_VIEW,
    "https://www.example.com/$id".toUri(),
    context,
    MyActivity::class.java
)

val deepLinkPendingIntent: PendingIntent? = TaskStackBuilder.create(context).run {
    addNextIntentWithParentStack(deepLinkIntent)
    getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT)
}

Vous pouvez ensuite utiliser ce deepLinkPendingIntent comme n'importe quel autre PendingIntent afin d'ouvrir votre application à l'emplacement de destination du lien profond.

Navigation imbriquée

Pour en savoir plus sur la création de graphiques de navigation imbriqués, consultez la section Graphiques imbriqués.

Intégration avec la barre de navigation inférieure

En définissant NavController à un niveau supérieur dans votre hiérarchie de composables, vous pouvez connecter Navigation à d'autres composants, comme le composant de navigation en bas de l'écran. Cela vous permet de naviguer en sélectionnant les icônes dans la barre inférieure.

Pour utiliser les composants BottomNavigation et BottomNavigationItem, ajoutez la dépendance androidx.compose.material à votre application Android.

Groovy

dependencies {
    implementation "androidx.compose.material:material:1.6.4"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.11"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

dependencies {
    implementation("androidx.compose.material:material:1.6.4")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.11"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Pour associer les éléments d'une barre de navigation inférieure aux itinéraires de votre graphique de navigation, nous vous recommandons de définir une classe scellée, comme Screen ici. Elle contient l'itinéraire et l'ID de ressource de chaîne des destinations.

sealed class Screen(val route: String, @StringRes val resourceId: Int) {
    object Profile : Screen("profile", R.string.profile)
    object FriendsList : Screen("friendslist", R.string.friends_list)
}

Placez ensuite ces éléments dans une liste pouvant être utilisée par BottomNavigationItem :

val items = listOf(
   Screen.Profile,
   Screen.FriendsList,
)

Dans votre composable BottomNavigation, obtenez le NavBackStackEntry actuel en utilisant la fonction currentBackStackEntryAsState(). Cette entrée vous donne accès au NavDestination actuel. L'état sélectionné de chaque BottomNavigationItem peut ensuite être déterminé en comparant l'itinéraire de l'élément avec l'itinéraire de la destination actuelle et ses destinations parentes afin de gérer les cas où vous utilisez la navigation imbriquée à l'aide de la hiérarchie NavDestination.

L'itinéraire de l'élément est également utilisé pour connecter le lambda onClick à un appel navigate afin que l'utilisateur puisse appuyer sur l'élément pour y accéder. Grâce aux options saveState et restoreState, l'état et la pile "Retour" de cet élément sont correctement enregistrés et restaurés lorsque vous passez d'un élément de navigation à l'autre en bas de l'écran.

val navController = rememberNavController()
Scaffold(
  bottomBar = {
    BottomNavigation {
      val navBackStackEntry by navController.currentBackStackEntryAsState()
      val currentDestination = navBackStackEntry?.destination
      items.forEach { screen ->
        BottomNavigationItem(
          icon = { Icon(Icons.Filled.Favorite, contentDescription = null) },
          label = { Text(stringResource(screen.resourceId)) },
          selected = currentDestination?.hierarchy?.any { it.route == screen.route } == true,
          onClick = {
            navController.navigate(screen.route) {
              // Pop up to the start destination of the graph to
              // avoid building up a large stack of destinations
              // on the back stack as users select items
              popUpTo(navController.graph.findStartDestination().id) {
                saveState = true
              }
              // Avoid multiple copies of the same destination when
              // reselecting the same item
              launchSingleTop = true
              // Restore state when reselecting a previously selected item
              restoreState = true
            }
          }
        )
      }
    }
  }
) { innerPadding ->
  NavHost(navController, startDestination = Screen.Profile.route, Modifier.padding(innerPadding)) {
    composable(Screen.Profile.route) { Profile(navController) }
    composable(Screen.FriendsList.route) { FriendsList(navController) }
  }
}

Ici, vous allez exploiter la méthode NavController.currentBackStackEntryAsState() pour hisser l'état navController de la fonction NavHost, puis le partager avec le composant BottomNavigation. Cela signifie que BottomNavigation possède automatiquement l'état le plus récemment mis à jour.

Sûreté du typage dans Navigation Compose

Le code de cette page n'utilise pas la sûreté du typage. Vous pouvez appeler la fonction navigate() avec des routes inexistantes ou des arguments incorrects. Cependant, vous pouvez structurer votre code de navigation pour qu'il soit sûr lors de l'exécution. Cela vous permet d'éviter les plantages et de vous assurer que :

  • les arguments que vous fournissez lorsque vous accédez à une destination ou un graphique de navigation sont de types appropriés, et que tous les arguments requis sont présents ;f
  • les arguments que vous récupérez à partir de SavedStateHandle sont de types appropriés.

Pour en savoir plus à ce sujet, consultez la section Sûreté du typage dans le DSL Kotlin et Navigation Compose.

Interopérabilité

Si vous souhaitez utiliser le composant Navigation avec Compose, deux options s'offrent à vous :

  • Définissez un graphique de navigation avec le composant Navigation pour les fragments.
  • Définissez un graphique de navigation avec un NavHost dans Compose en utilisant les destinations Compose. Cela n'est possible que si tous les écrans du graphique de navigation sont des composables.

Pour les applications qui utilisent à la fois les vues et Compose, nous vous recommandons donc d'utiliser le composant Navigation basé sur des fragments. Les fragments contiendront ensuite les écrans basés sur les vues, les écrans Compose et les écrans qui utilisent à la fois les vues et Compose. Une fois que le contenu de chaque fragment est dans Compose, l'étape suivante consiste à lier tous ces écrans à Navigation Compose et à supprimer tous les fragments.

Pour modifier des destinations dans le code Compose, vous exposez des événements pouvant être transmis à n'importe quel composable de la hiérarchie et déclenchés par ceux-ci :

@Composable
fun MyScreen(onNavigate: (Int) -> Unit) {
    Button(onClick = { onNavigate(R.id.nav_profile) } { /* ... */ }
}

Dans votre fragment, vous créez le pont entre Compose et le composant de navigation basé sur des fragments en recherchant NavController et en accédant à la destination :

override fun onCreateView( /* ... */ ) {
    setContent {
        MyScreen(onNavigate = { dest -> findNavController().navigate(dest) })
    }
}

Vous pouvez également transmettre l'élément NavController à votre hiérarchie Compose. Toutefois, l'exposition de fonctions simples est beaucoup plus réutilisable et testable.

Test

Dissociez le code de navigation de vos destinations de composables pour pouvoir tester chaque composable séparément, indépendamment du composable NavHost.

Cela signifie que vous ne devez pas transmettre le navController directement dans un composable, mais transmettre des rappels de navigation en tant que paramètres. Cela permet de tester individuellement tous vos composables, car ils ne nécessitent pas d'instance de navController lors des tests.

Le niveau d'indirection fourni par le lambda composable vous permet de séparer votre code de navigation du composable lui-même. Cela fonctionne dans deux sens :

  • transmettre des arguments analysés dans votre composable uniquement ;
  • transmettre des lambdas qui doivent être déclenchés par le composable pour naviguer, plutôt que le NavController lui-même.

Par exemple, un composable Profile qui accepte un userId en entrée et permet aux utilisateurs d'accéder à la page de profil d'un ami peut avoir la signature suivante:

@Composable
fun Profile(
    userId: String,
    navigateToFriendProfile: (friendUserId: String) -> Unit
) {
 …
}

De cette façon, le composable Profile fonctionne indépendamment de la navigation, ce qui lui permet d'être testé séparément. Le lambda composable encapsule la logique minimale requise pour combler l'écart entre les API de navigation et votre composable :

composable(
    "profile?userId={userId}",
    arguments = listOf(navArgument("userId") { defaultValue = "user1234" })
) { backStackEntry ->
    Profile(backStackEntry.arguments?.getString("userId")) { friendUserId ->
        navController.navigate("profile?userId=$friendUserId")
    }
}

Nous vous recommandons d'écrire des tests qui couvrent les besoins de votre application en matière de navigation. Pour ce faire, testez le NavHost, les actions de navigation transmises à vos composables ainsi qu'à vos composables d'écran individuels.

Tester le NavHost

Pour commencer à tester votre NavHost , ajoutez la dépendance navigation-testing suivante:

dependencies {
// ...
  androidTestImplementation "androidx.navigation:navigation-testing:$navigationVersion"
  // ...
}

Vous pouvez configurer l'objet de test NavHost et lui transmettre une instance de l'instance navController. Pour ce faire, l'artefact de test de navigation fournit un TestNavHostController. Voici à quoi ressemble votre test d'UI qui vérifie la destination de départ de votre application et le NavHost :

class NavigationTest {

    @get:Rule
    val composeTestRule = createComposeRule()
    lateinit var navController: TestNavHostController

    @Before
    fun setupAppNavHost() {
        composeTestRule.setContent {
            navController = TestNavHostController(LocalContext.current)
            navController.navigatorProvider.addNavigator(ComposeNavigator())
            AppNavHost(navController = navController)
        }
    }

    // Unit test
    @Test
    fun appNavHost_verifyStartDestination() {
        composeTestRule
            .onNodeWithContentDescription("Start Screen")
            .assertIsDisplayed()
    }
}

Tester les actions de navigation

Vous pouvez tester l'implémentation de la navigation de différentes manières : en cliquant sur les éléments de l'UI, puis en vérifiant la destination affichée ou en comparant l'itinéraire attendu par rapport à l'itinéraire actuel.

Pour tester l'implémentation concrète de votre application, il est préférable de tester les clics sur les éléments de l'UI. Pour découvrir comment procéder de manière isolée avec des fonctions modulables individuelles, consultez l'atelier de programmation Tests dans Jetpack Compose.

Vous pouvez également utiliser navController pour vérifier vos assertions en comparant l'itinéraire de la chaîne actuelle à celui attendu, à l'aide du currentBackStackEntry de navController :

@Test
fun appNavHost_clickAllProfiles_navigateToProfiles() {
    composeTestRule.onNodeWithContentDescription("All Profiles")
        .performScrollTo()
        .performClick()

    val route = navController.currentBackStackEntry?.destination?.route
    assertEquals(route, "profiles")
}

Pour en savoir plus sur les principes de base des tests Compose, consultez Tester votre mise en page Compose et l'atelier de programmation Tester dans Jetpack Compose. Pour en savoir plus sur les tests avancés du code de navigation, consultez le guide intitulé Tester la navigation.

En savoir plus

Pour en savoir plus sur le composant Navigation de Jetpack, consultez Premiers pas avec le composant Navigation ou suivez l'atelier de programmation sur la navigation Jetpack Compose.

Pour découvrir comment concevoir la navigation de votre application pour l'adapter à différentes tailles d'écran, orientations et facteurs de forme, consultez la page Navigation pour les interfaces utilisateur responsives.

Pour en savoir plus sur l'implémentation plus avancée de la navigation Compose dans une application modularisée, y compris des concepts tels que les graphiques imbriqués et l'intégration de la barre de navigation inférieure, consultez l'application Now in Android sur GitHub.

Exemples