Raggiungere una destinazione

Il componente Navigazione fornisce un modo diretto e generico per raggiungere una destinazione. Questa interfaccia supporta vari 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 Navigazione per raggiungere una destinazione in diversi contesti.

Utilizza un NavController

Il tipo di chiave che utilizzi per spostarti tra le destinazioni è NavController. Per saperne di più sulla classe stessa e su come creare un'istanza, consulta Creare un controller di navigazione. Questa guida illustra nei dettagli come utilizzarlo.

Indipendentemente dal framework UI utilizzato, puoi utilizzare una sola funzione per passare a una destinazione: NavController.navigate().

Sono disponibili molti sovraccarichi per navigate(). Il sovraccarico che devi scegliere corrisponde al tuo contesto esatto. Ad esempio, dovresti utilizzare un sovraccarico quando accedi a un componibile e un altro quando accedi a una vista.

Le seguenti sezioni descrivono alcuni dei principali sovraccarichi di navigate() che puoi utilizzare.

Accedere a un componibile.

Per accedere a un componibile nel grafico di navigazione, utilizza NavController.navigate(route). Con questo sovraccarico, navigate() accetta un singolo argomento String. Questo è il route. Serve come chiave per una destinazione.

navController.navigate("friendslist")

Per navigare utilizzando una stringa route, devi prima creare il tuo NavGraph in modo che ogni destinazione sia associata a un route. Per i componibili, puoi farlo con la funzione composable().

Per ulteriori informazioni, consulta Raggiungere una destinazione.

Quando una funzione componibile deve aprire una nuova schermata, non devi passare un riferimento a NavController in modo che possa chiamare direttamente navigate(). Secondo i principi della funzione Unidirectional Data Flow (UDF), il componibile dovrebbe esporre un evento gestito da NavController.

In parole povere, il componibile dovrebbe avere un parametro di tipo () -> Unit. Quando aggiungi destinazioni al tuo NavHost con la funzione composable(), trasmetti la chiamata componibile a NavController.navigate().

Per un esempio chiaro, consulta la sottosezione che segue.

Come dimostrazione della sezione precedente, osserva questi punti nello snippet seguente:

  1. Il componibile MyAppNavHost contiene l'istanza NavController.
  2. Di conseguenza, le chiamate a navigate() dovrebbero avvenire in quella posizione e non in un componibile inferiore come ProfileScreen.
  3. ProfileScreen contiene un pulsante che, facendo clic, indirizza l'utente a FriendsList. Tuttavia, non chiama navigate() stesso.
  4. Il pulsante chiama invece una funzione esposta come parametro onNavigateToFriends.
  5. Quando MyAppNavHost aggiunge ProfileScreen al grafico di navigazione, per onNavigateToFriends supera una funzione lambda che chiama navigate().
  6. In questo modo, quando l'utente preme il pulsante ProfileScreen, l'utente naviga correttamente su friendsList.
@Composable
fun MyAppNavHost(
    modifier: Modifier = Modifier,
    navController: NavHostController = rememberNavController(),
    startDestination: String = "profile"
) {
    NavHost(
        modifier = modifier,
        navController = navController,
        startDestination = startDestination
    ) {
        composable("profile") {
            ProfileScreen(
                onNavigateToFriends = { navController.navigate("friendsList") },
                /*...*/
            )
        }
        composable("friendslist") { FriendsListScreen(/*...*/) }
    }
}

@Composable
fun ProfileScreen(
    onNavigateToFriends: () -> Unit,
    /*...*/
) {
    /*...*/
    Button(onClick = onNavigateToFriends) {
        Text(text = "See friends list")
    }
}

Naviga utilizzando l'ID numero intero

Per raggiungere una destinazione utilizzando un ID numero intero, chiama l'overload navigate(int). Prende l'ID risorsa di un'azione o di una destinazione. Il seguente snippet di codice mostra come utilizzare questo sovraccarico per accedere 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 informazioni aggiuntive nel grafico di navigazione, mostrando visivamente in che modo le destinazioni si connettono tra loro.

Navigare con NavDeepLinkRequest

Per accedere a una destinazione del link diretto 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 con ID azione o destinazione, puoi passare a qualsiasi link diretto nel grafico, indipendentemente dal fatto che la destinazione sia visibile. Puoi raggiungere una destinazione nel grafico corrente o una destinazione su un grafico completamente diverso.

Azioni e tipi MIME

Oltre a Uri, NavDeepLinkRequest supporta anche i link diretti 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 elemento NavDeepLinkRequest corrisponda correttamente a una destinazione del link diretto implicito, l'URI, l'azione e il tipo MIME devono corrispondere tutti al valore 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/\*

Ulteriori contesti

Questo documento spiega come utilizzare NavController.navigate() nei casi d'uso più comuni. Tuttavia, la funzione presenta una serie di sovraccarichi che puoi utilizzare in diversi contesti e in tandem con qualsiasi framework Ui. Consulta la documentazione di riferimento per ulteriori dettagli su questi sovraccarichi.

Continua a leggere

Per ulteriori informazioni, consulta le seguenti pagine: