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.
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:
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 unNavGraph
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 elementoNavGraph
e trasmetterlo direttamente aNavHost
.
- Come parte di NavHost: crea il grafico di navigazione direttamente
come parte dell'aggiunta di
- 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 suNavHostFragment
.- La funzione
createGraph()
utilizzata con la DSL Kotlin sia per i frammenti sia per Compose è la stessa.
- La funzione
- 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.
- In modo programmatico: utilizza il DSL Kotlin per creare un
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.
}
- Un oggetto serializzabile rappresenta ciascuna delle due route,
Profile
eFriendsList
. - La chiamata al componibile
NavHost
trasmette unNavController
e una route per la destinazione di partenza. - La funzione lambda passata a
NavHost
chiamaNavController.createGraph()
e restituisceNavGraph
. - Ogni route viene fornita come argomento di tipo a
NavGraphBuilder.composable<T>()
, che aggiunge la destinazione alNavGraph
risultante. - Il lambda passato a
composable
è ciò che mostraNavHost
per quella 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)
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.
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 pername
. - La destinazione stessa è il blocco
composable<Profile>{}
. - Il componibile
ProfileScreen
prende il valore diprofile.name
per il proprio argomentoname
. - Di conseguenza, il valore
"John Smith"
passa aProfileScreen
.
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()
.
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.
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.
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.