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 i collegamenti tra di esse.

Tipi di destinazione

Esistono tre tipi generali di destinazioni: ospitata, finestra di dialogo e attività. La seguente tabella illustra questi tre tipi di destinazioni 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 in 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à

Rappresentano schermate o funzionalità uniche all'interno dell'app.

Fungono da punto di uscita al grafico di navigazione che avvia una nuova attività su Android gestita separatamente dal componente Navigazione.

Nello sviluppo di Android moderno, un'app è costituita da una singola attività. Pertanto, le destinazioni delle attività sono utilizzate al meglio quando si interagisce 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:

Framework

Sebbene lo stesso flusso di lavoro generale si applichi a tutti i casi, il modo esatto in cui crei un host di navigazione e un grafico dipende dal framework dell'interfaccia utente utilizzato.

  • Scrivi:utilizza il componibile NavHost. Crea un elemento NavGraph utilizzando la DSL Kotlin. Puoi creare il grafico in due modi:
    • Come parte di NavHost: crea il grafico di navigazione direttamente durante l'aggiunta del componente NavHost.
    • In modo programmatico: usa il metodo NavController.createGraph() per creare una NavGraph e passarla direttamente al NavHost.
  • Frammenti: se utilizzi frammenti con il framework dell'interfaccia utente delle visualizzazioni, utilizza NavHostFragment come host. Esistono diversi modi per creare un grafico di navigazione:
    • In modo programmatico: usa Kotlin DSL per creare una NavGraph e applicarla direttamente su NavHostFragment.
      • La funzione createGraph() utilizzata con la DSL di Kotlin per i frammenti e per Compose è la stessa.
    • XML: scrivi l'host di navigazione e il grafico direttamente in XML.
    • Editor di Android Studio: usa l'editor GUI in Android Studio per creare e modificare il grafico come file di risorse XML.

Scrivi

In Scrivi, utilizza la NavHost componibile per creare il grafico di navigazione. Considera il seguente esempio:

val navController = rememberNavController()

NavHost(navController = navController, startDestination = "profile") {
    composable("profile") { Profile( /* ... */ ) }
    composable("friendslist") { FriendsList( /* ... */ ) }
    // Add more destinations similarly.
}
  1. La chiamata alla componibile NavHost passa una stringa NavController e route che corrisponde alla destinazione iniziale.
  2. La funzione lambda passata all'NavHost alla fine chiama NavController.creatGraph() e restituisce NavGraph.
  3. Le chiamate a NavGraphBuilder.composable() aggiungono destinazioni al NavGraph risultante.
  4. In questo caso, le destinazioni sono i componibili Profile e FriendsList. Le stringhe di route "profile" e "friendslist" diventano le chiavi che identificano le due destinazioni.

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

val navGraph by remember(navController) {
  navController.createGraph(startDestination = "profile") {
    composable("profile") { Profile() }
    composable("friendslist") { FriendsList() }
  }
}
NavHost(navController, navGraph)

Esempio minimo

Un esempio minimo ma completo di NavController e NavHost che lavorano insieme:

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

// Define the FriendsList composable.
@Composable
fun FriendsList(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") {
    composable("profile") { Profile(onNavigateToFriendsList = { navController.navigate("friendslist") }) }
    composable("friendslist") { FriendsList(onNavigateToProfile = { navController.navigate("profile") }) }
  }
}

Come mostra lo snippet, invece di passare NavController ai tuoi componibili, espone un evento a NavHost. In altre parole, i componibili devono avere un parametro di tipo () -> Unit per il quale NavHost passa una funzione lambda che chiama NavController.navigate().

Frammenti

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

Le sezioni seguenti descrivono in dettaglio questi diversi approcci.

In modo programmatico

Il DSL di Kotlin offre un modo programmatico per creare un grafico di navigazione con frammenti. Per molti versi, questa procedura è 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>

Successivamente, passa il id del 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:

// 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"
) {
    // 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.
}

Utilizzare DSL in questo modo è molto simile al flusso di lavoro descritto nella precedente sezione su Scrivi. Ad esempio, sia qui che qui, la funzione NavController.createGraph() genera NavGraph. Allo stesso modo, mentre NavGraphBuilder.composable() aggiunge destinazioni componibili al grafico, qui NavGraphBuilder.fragment() aggiunge una destinazione del frammento.

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

XML

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

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

Un'implementazione minima di 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 di navigazione. Di seguito è riportato un esempio di come 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>

Puoi utilizzare le azioni per definire le connessioni tra destinazioni diverse. In questo esempio, il frammento profile contiene un'azione che porta a friendslist. Per ulteriori informazioni, consulta Utilizzare azioni e frammenti di navigazione.

Editor

Puoi gestire il grafico di navigazione dell'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, consulta l'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 ulteriori concetti di navigazione principali, consulta le seguenti guide: