La navigazione consente di allegare dati a un'operazione di navigazione definendo gli argomenti per una destinazione. Ad esempio, una destinazione del profilo utente potrebbe accettare un argomento ID utente per determinare quale utente visualizzare.
In generale, è consigliabile passare solo la quantità minima di dati tra le destinazioni. Ad esempio, devi passare una chiave per recuperare un oggetto anziché passare l'oggetto stesso, poiché lo spazio totale per tutti gli stati salvati è limitato su Android. Se devi passare grandi quantità di dati, utilizza un ViewModel come descritto nella panoramica di ViewModel.
Definisci gli argomenti di destinazione
Per passare i dati tra le destinazioni, devi prima definire l'argomento aggiungendolo alla destinazione che lo riceve seguendo questi passaggi:
- Nell'Editor di navigazione, fai clic sulla destinazione che riceve l'argomento.
- Nel riquadro Attributi, fai clic su Aggiungi (+).
- Nella finestra Aggiungi link argomento visualizzata, inserisci il nome dell'argomento, il tipo di argomento, se l'argomento è nullable e un valore predefinito, se necessario.
- Fai clic su Aggiungi. Tieni presente che l'argomento ora viene visualizzato nell'elenco Argomenti nel riquadro Attributi.
- Poi, fai clic sull'azione corrispondente che ti porta a questa destinazione. Nel riquadro Attributi, ora dovresti vedere l'argomento appena aggiunto nella sezione Valori predefiniti degli argomenti.
Puoi anche vedere che l'argomento è stato aggiunto in XML. Fai clic sulla scheda Testo per passare alla visualizzazione XML e nota che l'argomento è stato aggiunto alla destinazione che lo riceve. Di seguito è riportato un esempio:
<fragment android:id="@+id/myFragment" > <argument android:name="myArg" app:argType="integer" android:defaultValue="0" /> </fragment>
Tipi di argomenti supportati
La libreria Navigation supporta i seguenti tipi di argomenti:
| Tipo | Sintassi app:argType | Supporto per i valori predefiniti | Gestito dalle route | Ammette valori Null |
|---|---|---|---|---|
| Numero intero | app:argType="integer" | Sì | Sì | No |
| In virgola mobile | app:argType="float" | Sì | Sì | No |
| Lungo | app:argType="long" | Sì: i valori predefiniti devono sempre terminare con il suffisso "L" (ad es. "123L"). | Sì | No |
| Booleano | app:argType="boolean" | Sì: "true" o "false" | Sì | No |
| Stringa | app:argType="string" | Sì | Sì | Sì |
| Riferimento risorsa | app:argType="reference" | Sì: i valori predefiniti devono essere nel formato "@resourceType/resourceName" (ad es. "@style/myCustomStyle") o "0" | Sì | No |
| Parcelable personalizzato | app:argType="<type>", dove <type> è il nome completo della classe di Parcelable |
Supporta un valore predefinito "@null". Non supporta altri valori predefiniti. | No | Sì |
| Custom Serializable | app:argType="<type>", dove <type> è il nome completo della classe di Serializable |
Supporta un valore predefinito "@null". Non supporta altri valori predefiniti. | No | Sì |
| Enum personalizzato | app:argType="<type>", dove <type> è il nome completo dell'enum | Sì: i valori predefiniti devono corrispondere al nome non qualificato (ad es. "SUCCESS" per corrispondere a MyEnum.SUCCESS). | No | No |
Se un tipo di argomento supporta i valori null, puoi dichiarare un valore predefinito null utilizzando android:defaultValue="@null".
Le route, i deep link e gli URI con i relativi argomenti possono essere analizzati dalle stringhe. Questo non è possibile utilizzando tipi di dati personalizzati come Parcelable e Serializable, come mostrato nella tabella precedente. Per passare dati complessi personalizzati, archiviali altrove, ad esempio in un ViewModel o in un database, e passa solo un identificatore durante la navigazione; quindi recupera i dati nella nuova posizione al termine della navigazione.
Quando scegli uno dei tipi personalizzati, viene visualizzata la finestra di dialogo Seleziona classe, che ti chiede di scegliere la classe corrispondente per quel tipo. La scheda Progetto ti consente di scegliere una classe dal progetto corrente.
Puoi scegliere <inferred type> per consentire alla libreria Navigation di determinare il tipo in base al valore fornito.
Puoi selezionare Array per indicare che l'argomento deve essere un array del valore Tipo selezionato. Tieni presente quanto segue:
- Gli array di enum e gli array di riferimenti alle risorse non sono supportati.
- Gli array supportano i valori nullable, indipendentemente dal supporto dei valori nullable del tipo sottostante. Ad esempio, l'utilizzo di
app:argType="integer[]"ti consente di utilizzareapp:nullable="true"per indicare che è accettabile passare un array null. - Gli array supportano un singolo valore predefinito, "@null". Gli array non supportano altri valori predefiniti.
Esegui l'override di un argomento di destinazione in un'azione
Gli argomenti a livello di destinazione e i valori predefiniti vengono utilizzati da tutte le azioni che indirizzano alla destinazione. Se necessario, puoi eseguire l'override del valore predefinito di un argomento (o impostarne uno se non esiste già) definendo un argomento a livello di azione. Questo argomento deve avere lo stesso nome e lo stesso tipo dell'argomento dichiarato nella destinazione.
Il seguente XML dichiara un'azione con un argomento che esegue l'override dell'argomento a livello di destinazione dell'esempio precedente:
<action android:id="@+id/startMyFragment"
app:destination="@+id/myFragment">
<argument
android:name="myArg"
app:argType="integer"
android:defaultValue="1" />
</action>
Utilizza Safe Args per trasmettere i dati con la sicurezza dei tipi
Il componente Navigation ha un plug-in Gradle chiamato Safe Args che genera classi di oggetti e builder semplici per la navigazione sicura dei tipi e l'accesso a tutti gli argomenti associati. Safe Args è vivamente consigliato per la navigazione e il passaggio di dati, perché garantisce la sicurezza dei tipi.
Se non utilizzi Gradle, non puoi utilizzare il plug-in Safe Args. In questi casi, puoi utilizzare i bundle per passare direttamente i dati.
Per aggiungere Safe Args
al tuo progetto, includi il seguente classpath nel file build.gradle di primo livello:
Groovy
buildscript { repositories { google() } dependencies { def nav_version = "2.10.2" classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version" } }
Kotlin
buildscript { repositories { google() } dependencies { val nav_version = "2.10.2" classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version") } }
Devi anche applicare uno dei due plug-in disponibili.
Per generare codice del linguaggio Java adatto a moduli Java o misti Java e Kotlin, aggiungi
questa riga al file build.gradle della tua app o del tuo modulo:
Groovy
plugins { id 'androidx.navigation.safeargs' }
Kotlin
plugins { id("androidx.navigation.safeargs") }
In alternativa, per generare codice Kotlin adatto a moduli solo Kotlin, aggiungi:
Groovy
plugins { id 'androidx.navigation.safeargs.kotlin' }
Kotlin
plugins { id("androidx.navigation.safeargs.kotlin") }
Devi avere android.useAndroidX=true nel tuo
file gradle.properties come indicato in
Migrazione ad AndroidX.
Dopo aver attivato Safe Args, il codice generato contiene le seguenti classi e i seguenti metodi con sicurezza dei tipi per ogni azione, nonché per ogni destinazione di invio e ricezione.
Viene creata una classe per ogni destinazione da cui ha origine un'azione. Il nome di questa classe è il nome della destinazione di origine seguito dalla parola "Directions". Ad esempio, se la destinazione di origine è un frammento denominato
SpecifyAmountFragment, la classe generata si chiamaSpecifyAmountFragmentDirections.Questa classe ha un metodo per ogni azione definita nella destinazione di origine.
Per ogni azione utilizzata per passare l'argomento, viene creata una classe interna il cui nome si basa sull'azione. Ad esempio, se l'azione si chiama
confirmationAction,, la classe si chiamaConfirmationAction. Se l'azione contiene argomenti senzadefaultValue, utilizza la classe di azione associata per impostare il valore degli argomenti.Viene creata una classe per la destinazione di ricezione. Il nome di questa classe è il nome della destinazione con l'aggiunta della parola "Args". Ad esempio, se il frammento di destinazione è denominato
ConfirmationFragment,, la classe generata è denominataConfirmationFragmentArgs. Utilizza il metodofromBundle()di questa classe per recuperare gli argomenti.
L'esempio seguente mostra come utilizzare questi metodi per impostare un argomento e passarlo al metodo navigate():
Kotlin
override fun onClick(v: View) {
val amountTv: EditText = view!!.findViewById(R.id.editTextAmount)
val amount = amountTv.text.toString().toInt()
val action = SpecifyAmountFragmentDirections.confirmationAction(amount)
v.findNavController().navigate(action)
}
Java
@Override
public void onClick(View view) {
EditText amountTv = (EditText) getView().findViewById(R.id.editTextAmount);
int amount = Integer.parseInt(amountTv.getText().toString());
ConfirmationAction action =
SpecifyAmountFragmentDirections.confirmationAction();
action.setAmount(amount);
Navigation.findNavController(view).navigate(action);
}
Nel codice della destinazione di ricezione, utilizza il metodo getArguments() per recuperare il bundle e utilizzarne i contenuti. Quando utilizzano le dipendenze -ktx, gli utenti di Kotlin possono anche utilizzare il delegato della proprietà by navArgs() per accedere agli argomenti.
Kotlin
val args: ConfirmationFragmentArgs by navArgs()
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
val tv: TextView = view.findViewById(R.id.textViewAmount)
val amount = args.amount
tv.text = amount.toString()
}
Java
@Override
public void onViewCreated(View view, @Nullable Bundle savedInstanceState) {
TextView tv = view.findViewById(R.id.textViewAmount);
int amount = ConfirmationFragmentArgs.fromBundle(getArguments()).getAmount();
tv.setText(amount + "");
}
Utilizza Safe Args con un'azione globale
Quando utilizzi Safe Args con un'azione globale, devi fornire un valore android:id per l'elemento <navigation> principale, come mostrato nell'esempio seguente:
<?xml version="1.0" encoding="utf-8"?> <navigation xmlns:app="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools" xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/main_nav" app:startDestination="@id/mainFragment"> ... </navigation>
Navigation genera una classe Directions per l'elemento <navigation> in base al valore android:id. Ad esempio, se hai un elemento <navigation> con android:id=@+id/main_nav, la classe generata si chiama MainNavDirections. Tutte le destinazioni all'interno dell'elemento <navigation> hanno
generato metodi per accedere a tutte le azioni globali associate utilizzando gli stessi
metodi descritti nella sezione precedente.
Passa i dati tra le destinazioni con gli oggetti Bundle
Se non utilizzi Gradle, puoi comunque passare argomenti tra le destinazioni utilizzando gli oggetti Bundle. Crea un oggetto Bundle e passalo alla destinazione utilizzando navigate(), come nell'esempio seguente:
Kotlin
val bundle = bundleOf("amount" to amount)
view.findNavController().navigate(R.id.confirmationAction, bundle)
Java
Bundle bundle = new Bundle();
bundle.putString("amount", amount);
Navigation.findNavController(view).navigate(R.id.confirmationAction, bundle);
Nel codice della destinazione di ricezione, utilizza il metodo getArguments() per recuperare Bundle e utilizzarne i contenuti:
Kotlin
val tv = view.findViewById<TextView>(R.id.textViewAmount)
tv.text = arguments?.getString("amount")
Java
TextView tv = view.findViewById(R.id.textViewAmount);
tv.setText(getArguments().getString("amount"));
Passa i dati alla destinazione iniziale
Puoi trasmettere dati alla destinazione iniziale della tua app. Innanzitutto, devi creare esplicitamente un Bundle che contenga i dati. Successivamente, utilizza uno dei seguenti approcci per passare Bundle alla destinazione iniziale:
- Se crei
NavHostin modo programmatico, chiamaNavHostFragment.create(R.navigation.graph, args), doveargsèBundleche contiene i tuoi dati. - In caso contrario, puoi impostare gli argomenti della destinazione di partenza chiamando uno dei seguenti overload di
NavController.setGraph():- Utilizza l'ID del grafico:
navController.setGraph(R.navigation.graph, args) - Utilizza il grafico stesso:
navController.setGraph(navGraph, args)
- Utilizza l'ID del grafico:
Per recuperare i dati nella destinazione di partenza, chiama
Fragment.getArguments().
Considerazioni su ProGuard
Se stai riducendo il codice, devi impedire che i nomi delle classi Parcelable, Serializable e Enum vengano offuscati durante il processo di minimizzazione. in uno di questi due modi:
- Utilizza le annotazioni @Keep.
- Utilizza le regole keepnames.
Le sottosezioni seguenti descrivono questi approcci.
Utilizza le annotazioni @Keep
L'esempio seguente aggiunge annotazioni @Keep alle definizioni delle classi del modello:
Kotlin
@Keep class ParcelableArg : Parcelable { ... }
@Keep class SerializableArg : Serializable { ... }
@Keep enum class EnumArg { ... }
Java
@Keep public class ParcelableArg implements Parcelable { ... }
@Keep public class SerializableArg implements Serializable { ... }
@Keep public enum EnumArg { ... }
Utilizza le regole keepnames
Puoi anche aggiungere regole keepnames al file proguard-rules.pro, come mostrato nell'esempio seguente:
proguard-rules.pro
...
-keepnames class com.path.to.your.ParcelableArg
-keepnames class com.path.to.your.SerializableArg
-keepnames class com.path.to.your.EnumArg
...
Risorse aggiuntive
Per saperne di più sulla navigazione, consulta le seguenti risorse aggiuntive.