Raggiungere una destinazione

Il componente Navigazione fornisce un modo semplice e generico per raggiungere una destinazione. Questa interfaccia supporta una serie di contesti e framework UI. Ad esempio, puoi utilizzare il componente Navigazione con Compose, visualizzazioni, frammenti, attività e persino framework UI personalizzati.

Questa guida descrive come utilizzare il componente di navigazione per raggiungere una destinazione in vari contesti.

Utilizzare un NavController

Il tipo di chiave che utilizzi per spostarti tra le destinazioni è NavController. Per saperne di più sulla classe e su come creare un'istanza, consulta Crea un controller di navigazione. Questa guida spiega in dettaglio come utilizzarlo.

Indipendentemente dal framework UI che utilizzi, esiste una singola funzione che puoi utilizzare per passare a una destinazione: NavController.navigate().

Sono disponibili molti sovraccarichi per navigate(). L'overload che devi scegliere corrisponde al tuo contesto esatto. Ad esempio, devi utilizzare un sovraccarico quando vai a un composable e un altro quando vai a una visualizzazione.

Le sezioni seguenti descrivono alcuni degli overload navigate() chiave che puoi utilizzare.

Vai a un composable

Per passare a un componibile, devi utilizzare NavController.navigate<T>. Con questo sovraccarico, navigate() accetta un singolo argomento route per il quale passi un tipo. Funge da chiave per una destinazione.

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

Per passare a un composable nel grafico di navigazione, definisci prima il tuo NavGraph in modo che ogni destinazione corrisponda a un tipo. Per i composable, puoi farlo con la funzione composable().

Esporre eventi dai composable

Quando una funzione componibile deve passare a una nuova schermata, non devi passargli un riferimento a NavController in modo che possa chiamare direttamente navigate(). Secondo i principi del flusso di dati unidirezionale (UDF), il composable dovrebbe invece esporre un evento gestito da NavController.

In altre parole, il tuo elemento componibile deve avere un parametro di tipo () -> Unit. Quando aggiungi destinazioni a NavHost con la funzione composable(), passa al tuo componibile una chiamata a NavController.navigate().

Per un esempio, consulta la sottosezione che segue.

Esempio

Come dimostrazione delle sezioni precedenti, osserva questi punti nello snippet seguente:

  1. Ogni destinazione nel grafico viene creata utilizzando una route, ovvero un oggetto o una classe serializzabile che descrive i dati richiesti da quella destinazione.
  2. Il componente componibile MyAppNavHost contiene l'istanza NavController.
  3. Di conseguenza, le chiamate a navigate() devono essere effettuate lì e non in un composable inferiore come ProfileScreen.
  4. ProfileScreen contiene un pulsante che indirizza l'utente a FriendsList quando viene selezionato. Tuttavia, non chiama navigate().
  5. Il pulsante chiama invece una funzione esposta come parametro onNavigateToFriends.
  6. Quando MyAppNavHost aggiunge ProfileScreen al grafico di navigazione, per onNavigateToFriends passa una lambda che chiama navigate(route = FriendsList).
  7. In questo modo, quando l'utente preme il pulsante ProfileScreen, viene indirizzato correttamente a 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")
    }
}

Navigare utilizzando l'ID intero

Per passare a una destinazione utilizzando un ID intero, chiama l'overload navigate(int). Accetta l'ID risorsa di un'azione o di una destinazione. Lo snippet di codice seguente mostra come utilizzare questo overload per passare a 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);
  }
});

Quando navighi utilizzando gli ID, devi utilizzare le azioni, se possibile. Le azioni forniscono ulteriori informazioni nel grafico di navigazione, mostrando visivamente come le tue destinazioni sono collegate tra loro.

Navigare utilizzando NavDeepLinkRequest

Per passare a una destinazione di deep link implicito, utilizza l'overload navigate(NavDeepLinkRequest). Lo snippet seguente fornisce un'implementazione di questo metodo:

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)

A differenza della navigazione tramite ID azione o destinazione, puoi navigare verso qualsiasi deep link nel tuo grafico, indipendentemente dal fatto che la destinazione sia visibile. Puoi navigare verso una destinazione sul grafico corrente o su un grafico completamente diverso.

Azioni e tipi MIME

Oltre a Uri, NavDeepLinkRequest supporta anche i deep link con azioni e tipi MIME. Per aggiungere un'azione alla richiesta, utilizza fromAction() o setAction(). Per aggiungere un tipo MIME a una richiesta, utilizza fromMimeType() o setMimeType().

Affinché un NavDeepLinkRequest corrisponda correttamente a una destinazione di deep link implicito, l'URI, l'azione e il tipo MIME devono corrispondere al NavDeepLink nella destinazione. Gli URI devono corrispondere al pattern, le azioni devono corrispondere esattamente e i tipi MIME devono essere correlati. Ad esempio, image/jpg corrisponde a image/\*

Altri contesti

Questo documento spiega come utilizzare NavController.navigate() nei casi d'uso più comuni. Tuttavia, la funzione ha una serie di overload che puoi utilizzare in contesti diversi e in combinazione con qualsiasi framework UI. Per ulteriori dettagli su questi overload, consulta la documentazione di riferimento.

Per approfondire

Per saperne di più, consulta le pagine seguenti: