Progetta il tuo grafico di navigazione

Il componente Navigazione utilizza un grafico di navigazione per gestire la navigazione nell'app. Il grafico di navigazione è una struttura di dati che contiene ogni destinazione all'interno dell'app e le connessioni tra loro.

Nota :il grafico di navigazione è diverso dallo stack back, che è uno stack all'interno di NavController che contiene le destinazioni che l'utente ha visitato di recente.

Tipi di destinazione

Esistono tre tipi generali di destinazioni: ospitate, di dialogo e attività. La seguente tabella illustra questi tre tipi di destinazione e i relativi scopi.

Tipo	Descrizione	Casi d'uso
Ospitato	Compila l'intero host di navigazione. In altre parole, le dimensioni di una destinazione ospitata corrispondono a quelle dell'host di navigazione e le destinazioni precedenti non sono visibili.	Schermate principali e dei dettagli.
Finestra di dialogo	Presenta i componenti dell'interfaccia utente overlay. Questa UI non è legata alla posizione dell'host di navigazione o alle sue dimensioni. Le destinazioni precedenti sono visibili sotto la destinazione.	Avvisi, selezioni, moduli.
Attività	Rappresenta schermate o funzionalità uniche all'interno dell'app.	Fungere da punto di uscita per il grafico di navigazione che avvia una nuova attività Android gestita separatamente dal componente Navigazione. Nello sviluppo di Android moderno, un'app è costituita da una singola attività. Le destinazioni delle attività sono quindi ideali per interagire con attività di terze parti o nell'ambito del processo di migrazione.

Questo documento contiene esempi di destinazioni ospitate, che sono le destinazioni più comuni e fondamentali. Consulta le seguenti guide per informazioni sulle altre destinazioni:

• Destinazioni delle finestre di dialogo
• Destinazioni delle attività

Framework

Anche se lo stesso flusso di lavoro generale si applica in tutti i casi, il modo in cui crei esattamente un host e un grafico di navigazione dipende dal framework dell'interfaccia utente che utilizzi.

• Scrivi: utilizza il componibile NavHost. Aggiungi un NavGraph utilizzando Kotlin DSL. Puoi creare il grafico in due modi:
  • Come parte di NavHost: crea il grafico di navigazione direttamente come parte dell'aggiunta di NavHost.
  • In modo programmatico: utilizza il metodo NavController.createGraph() per creare un elemento NavGraph e trasmetterlo direttamente a NavHost.
• Frammenti: quando utilizzi frammenti con il framework di UI delle viste, usa un NavHostFragment come host. Esistono diversi modi per creare un grafico di navigazione:
  • In modo programmatico: utilizza il DSL Kotlin per creare un NavGraph e applicarlo direttamente su NavHostFragment.
    • La funzione createGraph() utilizzata con la DSL Kotlin sia per i frammenti sia per Compose è la stessa.
  • XML: scrivi l'host di navigazione e il grafico direttamente in XML.
  • Editor di Android Studio: utilizza l'editor GUI in Android Studio per creare e modificare il grafico come file di risorsa XML.

Nota: il modo in cui interagisci con il grafico tramite NavController è simile tra i framework. Per ulteriori dettagli, consulta la guida Raggiungere una destinazione.

Scrittura

In Compose, utilizza un oggetto o una classe serializzabile per definire una route. Un percorso descrive come raggiungere una destinazione e contiene tutte le informazioni necessarie per la destinazione. Una volta definite le route, utilizza l'elemento componibile NavHost per creare il grafico di navigazione. Considera il seguente esempio:

@Serializable
object Profile
@Serializable
object FriendsList

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile) {
    composable<Profile> { ProfileScreen( /* ... */ ) }
    composable<FriendsList> { FriendsListScreen( /* ... */ ) }
    // Add more destinations similarly.
}

1. Un oggetto serializzabile rappresenta ciascuna delle due route, Profile e FriendsList.
2. La chiamata al componibile NavHost trasmette un NavController e una route per la destinazione di partenza.
3. La funzione lambda passata a NavHost chiama NavController.createGraph() e restituisce NavGraph.
4. Ogni route viene fornita come argomento di tipo a NavGraphBuilder.composable<T>(), che aggiunge la destinazione al NavGraph risultante.
5. Il lambda passato a composable è ciò che mostra NavHost per quella destinazione.

Attenzione: anziché trasmettere un tipo a composable(), puoi passare una stringa route o un numero intero id. Tuttavia, questo rende molto più difficile la gestione del passaggio di argomenti aggiuntivi alla destinazione.

Informazioni su lambda

Per comprendere meglio il lambda che crea NavGraph, tieni presente che per generare lo stesso grafico dello snippet precedente, puoi creare NavGraph separatamente utilizzando NavController.createGraph() e passarlo direttamente a NavHost:

val navGraph by remember(navController) {
  navController.createGraph(startDestination = Profile)) {
    composable<Profile> { ProfileScreen( /* ... */ ) }
    composable<FriendsList> { FriendsListScreen( /* ... */ ) }
  }
}
NavHost(navController, navGraph)

Importante: un elemento NavController è associato a un singolo NavHost componibile. NavHost fornisce l'accesso NavController al relativo grafico di navigazione. Quando utilizzi NavController per raggiungere una destinazione, NavController interagisce con il relativo NavHost associato.

Supera argomenti

Se devi passare dati a una destinazione, definisci la route con una classe con parametri. Ad esempio, la route Profile è una classe di dati con un parametro name.

@Serializable
data class Profile(val name: String)

Ogni volta che devi passare argomenti a quella destinazione, puoi creare un'istanza della classe di route, passando gli argomenti al costruttore della classe.

Nota: utilizza data class per una route con argomenti e object o data object per una route senza argomenti.

Ottieni istanza route

Puoi ottenere l'istanza della route con NavBackStackEntry.toRoute() o SavedStateHandle.toRoute(). Quando crei una destinazione utilizzando composable(), NavBackStackEntry è disponibile come parametro.

@Serializable
data class Profile(val name: String)

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile(name="John Smith")) {
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(name = profile.name) }
}

Tieni presente quanto segue in questo snippet:

• La route Profile specifica la destinazione di partenza nel grafico di navigazione, con "John Smith" come argomento per name.
• La destinazione stessa è il blocco composable<Profile>{}.
• Il componibile ProfileScreen prende il valore di profile.name per il proprio argomento name.
• Di conseguenza, il valore "John Smith" passa a ProfileScreen.

Esempio minimo

Un esempio completo di NavController e NavHost che lavorano insieme:

@Serializable
data class Profile(val name: String)

@Serializable
object FriendsList

// Define the ProfileScreen composable.
@Composable
fun ProfileScreen(
    profile: Profile
    onNavigateToFriendsList: () -> Unit,
  ) {
  Text("Profile for ${profile.name}")
  Button(onClick = { onNavigateToFriendsList() }) {
    Text("Go to Friends List")
  }
}

// Define the FriendsListScreen composable.
@Composable
fun FriendsListScreen(onNavigateToProfile: () -> Unit) {
  Text("Friends List")
  Button(onClick = { onNavigateToProfile() }) {
    Text("Go to Profile")
  }
}

// Define the MyApp composable, including the `NavController` and `NavHost`.
@Composable
fun MyApp() {
  val navController = rememberNavController()
  NavHost(navController, startDestination = Profile(name = "John Smith")) {
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(
            profile = profile,
            onNavigateToFriendsList = {
                navController.navigate(route = FriendsList)
            }
        )
    }
    composable<FriendsList> {
      FriendsListScreen(
        onNavigateToProfile = {
          navController.navigate(
            route = Profile(name = "Aisha Devi")
          )
        }
      )
    }
  }
}

Come dimostrato dallo snippet, invece di passare NavController ai componibili, esponi un evento all'elemento NavHost. In altre parole, gli elementi componibili devono avere un parametro di tipo () -> Unit per il quale NavHost passa una lambda che chiama NavController.navigate().

Nota: utilizzando i parametri della classe di route puoi passare i dati alla destinazione specifica con una sicurezza di tipo completa. Ad esempio, nel codice precedente Profile.name garantisce che name sia sempre un String.

Frammenti

Come descritto nelle sezioni precedenti, quando utilizzi i frammenti hai la possibilità di creare un grafico di navigazione in modo programmatico utilizzando l'editor per DSL, XML o Android Studio.

Le seguenti sezioni descrivono nel dettaglio questi diversi approcci.

Nota: il componente Navigazione è progettato per le app che hanno un'attività principale con più destinazioni di frammenti. L'attività principale è associata a un grafico di navigazione e contiene un elemento NavHostFragment responsabile dello scambio delle destinazioni, se necessario. In un'app con più destinazioni, ogni attività ha il proprio grafico di navigazione.

In modo programmatico

La DSL Kotlin offre un modo programmatico per creare un grafico di navigazione con frammenti. Questa procedura è per molti versi più ordinata e moderna rispetto all'utilizzo di un file di risorse XML.

Considera l'esempio seguente, che implementa un grafico di navigazione a due schermate.

Innanzitutto è necessario creare NavHostFragment, che non deve includere un elemento app:navGraph:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</FrameLayout>

Poi, passa id di NavHostFragment a NavController.findNavController. In questo modo il NavController viene associato a NavHostFragment.

Successivamente, la chiamata a NavController.createGraph() collega il grafico a NavController e, di conseguenza, anche a NavHostFragment:

@Serializable
data class Profile(val name: String)

@Serializable
object FriendsList

// Retrieve the NavController.
val navController = findNavController(R.id.nav_host_fragment)

// Add the graph to the NavController with `createGraph()`.
navController.graph = navController.createGraph(
    startDestination = Profile(name = "John Smith")
) {
    // Associate each destination with one of the route constants.
    fragment<ProfileFragment, Profile> {
        label = "Profile"
    }

    fragment<FriendsListFragment, FriendsList>() {
        label = "Friends List"
    }

    // Add other fragment destinations similarly.
}

L'utilizzo dell'DSL in questo modo è molto simile al flusso di lavoro descritto nella sezione precedente di Compose. Ad esempio, sia lì che qui, la funzione NavController.createGraph() genera il valore NavGraph. Allo stesso modo, se NavGraphBuilder.composable() aggiunge destinazioni componibili al grafico, in questo caso NavGraphBuilder.fragment() aggiunge una destinazione per frammento.

Per ulteriori informazioni su come utilizzare il DSL Kotlin, consulta la sezione Creare un grafico con il DSL NavGraphBuilder.

XML

Puoi scrivere direttamente l'XML. L'esempio seguente rispecchia ed è equivalente all'esempio a due schermate della sezione precedente.

Innanzitutto, crea un NavHostFragment. funge da host di navigazione, che contiene il grafico di navigazione effettivo.

Un'implementazione minima di un NavHostFragment:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:navGraph="@navigation/nav_graph" />

</FrameLayout>

NavHostFragment contiene l'attributo app:navGraph. Utilizza questo attributo per collegare il grafico di navigazione all'host della navigazione. Di seguito è riportato un esempio di come potresti implementare il grafico:

<navigation xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/nav_graph"
    app:startDestination="@id/profile">

    <fragment
        android:id="@+id/profile"
        android:name="com.example.ProfileFragment"
        android:label="Profile">

        <!-- Action to navigate from Profile to Friends List. -->
        <action
            android:id="@+id/action_profile_to_friendslist"
            app:destination="@id/friendslist" />
    </fragment>

    <fragment
        android:id="@+id/friendslist"
        android:name="com.example.FriendsListFragment"
        android:label="Friends List" />

    <!-- Add other fragment destinations similarly. -->
</navigation>

Le azioni consentono di definire le connessioni tra destinazioni diverse. In questo esempio, il frammento profile contiene un'azione che porta a friendslist. Per ulteriori informazioni, vedi Utilizzare le azioni e i frammenti di navigazione.

Nota: l'esempio di DSL non definisce le azioni perché non si applicano in quel contesto. Quando utilizzi la DSL, usa direttamente NavController.navigate().

Editor

Puoi gestire il grafico di navigazione della tua app utilizzando l'editor di navigazione in Android Studio. Si tratta essenzialmente di una GUI che puoi utilizzare per creare e modificare il tuo XML NavigationFragment, come illustrato nella sezione precedente.

Per ulteriori informazioni, vedi Editor di navigazione.

Grafici nidificati

Puoi anche utilizzare grafici nidificati. Ciò comporta l'uso di un grafico come destinazione della navigazione. Per ulteriori informazioni, consulta la sezione Grafici nidificati.

Per approfondire

Per altri concetti fondamentali sulla navigazione, consulta le seguenti guide:

• Panoramica: assicurati di leggere la panoramica generale del componente di navigazione.
• Destinazioni attività:esempi di come implementare le destinazioni che portano l'utente alle attività.
• Destinazioni di dialogo: esempi di come creare destinazioni che indirizzano l'utente a una finestra di dialogo.
• Raggiungere una destinazione: una guida dettagliata che spiega come spostarsi da una destinazione a un'altra.
• Grafici nidificati: una guida approfondita su come nidificare un grafico di navigazione all'interno di un altro.