Navigation avec Compose

Le composant Navigation est compatible avec Jetpack Créer des applications Vous pouvez naviguer entre les composables tout en tirant parti de l'infrastructure du composant Navigation caractéristiques.

Configuration

Pour prendre en charge Compose, utilisez la dépendance suivante dans le fichier Fichier build.gradle:

Groovy

dependencies {
    def nav_version = "2.8.0"

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

Kotlin

dependencies {
    val nav_version = "2.8.0"

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

Premiers pas

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

Pour savoir comment créer un NavController dans Compose, consultez la documentation de la section Créer un contrôleur de navigation.

Créer un NavHost

Pour savoir comment créer un NavHost dans Compose, consultez la section "Compose" de la section Concevoir votre graphique de navigation.

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

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() et puis spécifiez 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 qui sont responsables de accédant à la couche de données, utilisez le SavedStateHandle de 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 de Des 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. À rendre ces liens profonds accessibles en externe, vous devez ajouter <intent-filter> au fichier manifest.xml de votre application. Pour activer le deep learning de l'exemple précédent, vous devez ajouter le code suivant à l'intérieur de <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 plus d'informations sur la création de graphiques de navigation imbriqués, consultez 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 en bas sur la barre d'adresse.

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.7.1"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

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

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    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'article avec l'itinéraire de la destination actuelle et ses destinations parentes vers gérer les cas lorsque vous utilisez la navigation imbriquée à l'aide de la 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 méthode 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. Nouveau message.

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 contiennent alors des données écrans, écrans Compose et écrans qui utilisent à la fois les vues et Compose. Une fois par Le contenu du fragment se trouve dans Compose. L'étape suivante consiste à relier tous ces écrans. avec 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.

Tests

Dissociez le code de navigation de vos destinations de composables pour permettre les tests chaque composable séparément, séparément du composable NavHost.

Cela signifie que vous ne devez pas transmettre le navController directement à des et transmettent des rappels de navigation en tant que paramètres. Cela permet tous vos composables puissent être testés individuellement, car ils ne nécessitent pas Instance de navController dans les tests.

C'est le niveau d'indirection fourni par le lambda composable qui vous permet Séparez 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 comme entrée et autorise les utilisateurs qui accèdent à la page de profil d'un ami peuvent 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 le test de navigation suivant : la dépendance:

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 cela, la navigation artefact de test 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 les tests dans Jetpack Compose dans cet atelier de programmation. 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 découvrir une implémentation plus avancée de la navigation Compose dans un application modularisée, incluant des concepts tels que les graphiques imbriqués et la barre de navigation inférieure consultez l'application Now in Android sur GitHub.

Exemples