Trasmettere dati tra destinazioni

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:

  1. Nell'Editor di navigazione, fai clic sulla destinazione che riceve l'argomento.
  2. Nel riquadro Attributi, fai clic su Aggiungi (+).
  3. 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.
  4. Fai clic su Aggiungi. Tieni presente che l'argomento ora viene visualizzato nell'elenco Argomenti nel riquadro Attributi.
  5. 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.
  6. 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 utilizzare app: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 chiama SpecifyAmountFragmentDirections.

    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 chiama ConfirmationAction. Se l'azione contiene argomenti senza defaultValue, 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 è denominata ConfirmationFragmentArgs. Utilizza il metodo fromBundle() 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:

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.

Codelab

Video