Mit der Navigation können Sie Daten an einen Navigationsvorgang anhängen, indem Sie Argumente für ein Ziel definieren. Ein Nutzerprofilziel kann beispielsweise ein Nutzer-ID-Argument verwenden, um zu bestimmen, welcher Nutzer angezeigt werden soll.
Im Allgemeinen sollten Sie nur die minimale Datenmenge zwischen Zielen übergeben. Sie sollten beispielsweise einen Schlüssel übergeben, um ein Objekt abzurufen, anstatt das Objekt selbst zu übergeben, da der Gesamtspeicherplatz für alle gespeicherten Zustände unter Android begrenzt ist. Wenn Sie große Datenmengen übergeben müssen, verwenden Sie ein ViewModel, wie in der ViewModel-Übersicht beschrieben.
Zielargumente definieren
Wenn Sie Daten zwischen Zielen übergeben möchten, müssen Sie zuerst das Argument definieren. Fügen Sie es dazu dem Ziel hinzu, das es empfängt. Gehen Sie dazu so vor:
- Klicke im Navigationseditor auf das Ziel, das das Argument empfängt.
- Klicken Sie im Bereich Attribute auf Hinzufügen (+).
- Geben Sie im Fenster Argument-Link hinzufügen den Argumentnamen, den Argumenttyp, ob das Argument nullfähig ist und bei Bedarf einen Standardwert ein.
- Klicken Sie auf Hinzufügen. Das Argument wird jetzt im Bereich Attribute in der Liste Argumente angezeigt.
- Klicken Sie dann auf die entsprechende Aktion, die Sie zu diesem Ziel führt. Im Bereich Attribute sollte jetzt das neu hinzugefügte Argument im Abschnitt Standardwerte für Argumente angezeigt werden.
Sie können auch sehen, dass das Argument in XML hinzugefügt wurde. Klicken Sie auf den Tab Text, um zur XML-Ansicht zu wechseln. Beachten Sie, dass Ihr Argument dem Ziel hinzugefügt wurde, das das Argument empfängt. Hier ein Beispiel:
<fragment android:id="@+id/myFragment" > <argument android:name="myArg" app:argType="integer" android:defaultValue="0" /> </fragment>
Unterstützte Argumenttypen
Die Navigationsbibliothek unterstützt die folgenden Argumenttypen:
| Typ | app:argType-Syntax | Unterstützung für Standardwerte | Von Routen verarbeitet | Nullwerte zulässig |
|---|---|---|---|---|
| Ganzzahl | app:argType="integer" | Ja | Ja | Nein |
| Float | app:argType="float" | Ja | Ja | Nein |
| Lang | app:argType="long" | Ja – Standardwerte müssen immer mit dem Suffix „L“ enden (z.B. „123L“). | Ja | Nein |
| Boolesch | app:argType="boolean" | Ja – „true“ oder „false“ | Ja | Nein |
| String | app:argType="string" | Ja | Ja | Ja |
| Ressourcenreferenz | app:argType="reference" | Ja – Standardwerte müssen das Format „@resourceType/resourceName“ (z.B. „@style/myCustomStyle“) oder „0“ haben | Ja | Nein |
| Benutzerdefiniertes Parcelable | app:argType="<type>", wobei <type> der voll qualifizierte Klassenname des Parcelable ist |
Unterstützt den Standardwert „@null“. Andere Standardwerte werden nicht unterstützt. | Nein | Ja |
| Benutzerdefinierte Serialisierung | app:argType="<type>", wobei <type> der voll qualifizierte Klassenname des Serializable ist |
Unterstützt den Standardwert „@null“. Andere Standardwerte werden nicht unterstützt. | Nein | Ja |
| Benutzerdefinierte Aufzählung | app:argType="<type>", wobei <type> der vollständig qualifizierte Name des Enums ist | Ja – Standardwerte müssen mit dem nicht qualifizierten Namen übereinstimmen (z.B. „SUCCESS“ für MyEnum.SUCCESS). | Nein | Nein |
Wenn ein Argumenttyp Nullwerte unterstützt, können Sie mit android:defaultValue="@null" einen Standardwert von Null deklarieren.
Routen, Deeplinks und URIs mit ihren Argumenten können aus Strings geparst werden. Dies ist mit benutzerdefinierten Datentypen wie Parcelables und Serializables nicht möglich, wie in der vorherigen Tabelle zu sehen ist. Wenn Sie benutzerdefinierte komplexe Daten weitergeben möchten, speichern Sie die Daten an anderer Stelle, z. B. in einem ViewModel oder einer Datenbank, und übergeben Sie bei der Navigation nur eine Kennung. Rufen Sie die Daten dann nach Abschluss der Navigation am neuen Speicherort ab.
Wenn Sie einen der benutzerdefinierten Typen auswählen, wird das Dialogfeld Klasse auswählen angezeigt. Sie werden dann aufgefordert, die entsprechende Klasse für diesen Typ auszuwählen. Auf dem Tab Projekt können Sie eine Klasse aus Ihrem aktuellen Projekt auswählen.
Sie können <inferred type> auswählen, damit die Navigationsbibliothek den Typ anhand des angegebenen Werts bestimmt.
Sie können Array auswählen, um anzugeben, dass das Argument ein Array des ausgewählten Typ-Werts sein soll. Wichtige Hinweise:
- Arrays von Enums und Arrays von Ressourcenreferenzen werden nicht unterstützt.
- Arrays unterstützen Nullwerte, unabhängig davon, ob der zugrunde liegende Typ Nullwerte unterstützt. Wenn Sie beispielsweise
app:argType="integer[]"verwenden, können Sie mitapp:nullable="true"angeben, dass die Übergabe eines Null-Arrays zulässig ist. - Arrays unterstützen einen einzelnen Standardwert, „@null“. Arrays unterstützen keine anderen Standardwerte.
Zielargument in einer Aktion überschreiben
Argumente und Standardwerte auf Zielebene werden von allen Aktionen verwendet, die zum Ziel führen. Bei Bedarf können Sie den Standardwert eines Arguments überschreiben oder einen Wert festlegen, falls noch keiner vorhanden ist. Dazu definieren Sie ein Argument auf Aktionsebene. Dieses Argument muss denselben Namen und Typ wie das im Ziel deklarierte Argument haben.
Im folgenden XML-Code wird eine Aktion mit einem Argument deklariert, das das Argument auf Zielebene aus dem vorherigen Beispiel überschreibt:
<action android:id="@+id/startMyFragment"
app:destination="@+id/myFragment">
<argument
android:name="myArg"
app:argType="integer"
android:defaultValue="1" />
</action>
Safe Args verwenden, um Daten mit Typsicherheit zu übergeben
Die Navigationskomponente hat ein Gradle-Plug-in namens Safe Args, das einfache Objekt- und Builder-Klassen für die typsichere Navigation und den Zugriff auf alle zugehörigen Argumente generiert. Safe Args wird für die Navigation und die Übergabe von Daten dringend empfohlen, da es die Typsicherheit gewährleistet.
Wenn Sie Gradle nicht verwenden, können Sie das Safe Args-Plug-in nicht verwenden. In diesen Fällen können Sie Bundles verwenden, um Daten direkt zu übergeben.
Wenn Sie Safe Args in Ihr Projekt einfügen möchten, fügen Sie die folgende classpath in Ihre build.gradle-Datei auf oberster Ebene ein:
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") } }
Außerdem müssen Sie eines von zwei verfügbaren Plug-ins anwenden.
Wenn Sie Java-Sprachcode generieren möchten, der für Java- oder gemischte Java- und Kotlin-Module geeignet ist, fügen Sie diese Zeile in die build.gradle-Datei Ihrer App oder Ihres Moduls ein:
Groovy
plugins { id 'androidx.navigation.safeargs' }
Kotlin
plugins { id("androidx.navigation.safeargs") }
Wenn Sie stattdessen Kotlin-Code generieren möchten, der für reine Kotlin-Module geeignet ist, fügen Sie Folgendes hinzu:
Groovy
plugins { id 'androidx.navigation.safeargs.kotlin' }
Kotlin
plugins { id("androidx.navigation.safeargs.kotlin") }
Gemäß Zu AndroidX migrieren muss android.useAndroidX=true in Ihrer gradle.properties-Datei vorhanden sein.
Nachdem Sie Safe Args aktiviert haben, enthält der generierte Code die folgenden typsicheren Klassen und Methoden für jede Aktion sowie für jedes Sende- und Empfangsziel.
Für jedes Ziel, von dem eine Aktion ausgeht, wird eine Klasse erstellt. Der Name dieser Klasse ist der Name des ursprünglichen Ziels, gefolgt vom Wort „Directions“. Wenn das ursprüngliche Ziel beispielsweise ein Fragment mit dem Namen
SpecifyAmountFragmentist, heißt die generierte KlasseSpecifyAmountFragmentDirections.Diese Klasse hat eine Methode für jede Aktion, die im ursprünglichen Ziel definiert ist.
Für jede Aktion, die zum Übergeben des Arguments verwendet wird, wird eine innere Klasse erstellt, deren Name auf der Aktion basiert. Wenn die Aktion beispielsweise
confirmationAction,heißt, lautet der Name der KlasseConfirmationAction. Wenn Ihre Aktion Argumente ohnedefaultValueenthält, verwenden Sie die zugehörige Aktionsklasse, um den Wert der Argumente festzulegen.Für das Empfängerziel wird eine Klasse erstellt. Der Name dieser Klasse ist der Name des Ziels, gefolgt von „Args“. Wenn das Zielfragment beispielsweise
ConfirmationFragment,heißt, wird die generierte KlasseConfirmationFragmentArgsgenannt. Verwenden Sie die MethodefromBundle()dieser Klasse, um die Argumente abzurufen.
Im folgenden Beispiel wird gezeigt, wie Sie mit diesen Methoden ein Argument festlegen und an die Methode navigate() übergeben:
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);
}
Verwenden Sie im Code für das Empfängerziel die Methode getArguments(), um das Bundle abzurufen und seinen Inhalt zu verwenden. Wenn Sie die -ktx-Abhängigkeiten verwenden, können Kotlin-Nutzer auch den by navArgs()-Property-Delegaten verwenden, um auf Argumente zuzugreifen.
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 + "");
}
Safe Args mit einer globalen Aktion verwenden
Wenn Sie Safe Args mit einer globalen Aktion verwenden, müssen Sie einen android:id-Wert für das <navigation>-Stammelement angeben, wie im folgenden Beispiel gezeigt:
<?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>
Die Navigation generiert eine Directions-Klasse für das <navigation>-Element, die auf dem android:id-Wert basiert. Wenn Sie beispielsweise ein <navigation>-Element mit android:id=@+id/main_nav haben, heißt die generierte Klasse MainNavDirections. Für alle Ziele im Element <navigation> wurden Methoden für den Zugriff auf alle zugehörigen globalen Aktionen generiert. Dabei werden dieselben Methoden wie im vorherigen Abschnitt beschrieben verwendet.
Daten zwischen Zielen mit Bundle-Objekten übergeben
Wenn Sie Gradle nicht verwenden, können Sie Argumente mithilfe von Bundle-Objekten zwischen Zielen übergeben. Erstellen Sie ein Bundle-Objekt und übergeben Sie es mit navigate() an das Ziel, wie im folgenden Beispiel gezeigt:
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);
Verwenden Sie im Code des Empfangsziels die Methode getArguments(), um die Bundle abzurufen und ihren Inhalt zu verwenden:
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"));
Daten an das Startziel übergeben
Sie können Daten an das Startziel Ihrer App übergeben. Zuerst müssen Sie explizit ein Bundle erstellen, das die Daten enthält. Verwenden Sie als Nächstes einen der folgenden Ansätze, um die Bundle an das Startziel zu übergeben:
- Wenn Sie
NavHostprogrammatisch erstellen, rufen SieNavHostFragment.create(R.navigation.graph, args)auf, wobeiargsderBundleist, der Ihre Daten enthält. - Andernfalls können Sie Argumente für das Startziel festlegen, indem Sie eine der folgenden Überladungen von
NavController.setGraph()aufrufen:- Verwenden Sie die ID des Graphen:
navController.setGraph(R.navigation.graph, args) - Verwenden Sie das Diagramm selbst:
navController.setGraph(navGraph, args)
- Verwenden Sie die ID des Graphen:
Rufen Sie Fragment.getArguments() auf, um die Daten in Ihrem Startziel abzurufen.
Hinweise zu ProGuard
Wenn Sie Ihren Code verkleinern, müssen Sie verhindern, dass die Klassennamen Parcelable, Serializable und Enum im Rahmen der Minimierung verschleiert werden. Dafür stehen Ihnen zwei Möglichkeiten zur Verfügung:
- Verwenden Sie @Keep-Annotationen.
- Verwenden Sie „keepnames“-Regeln.
In den folgenden Unterabschnitten werden diese Ansätze beschrieben.
@Keep-Annotationen verwenden
Im folgenden Beispiel werden den Modellklassendefinitionen @Keep-Annotationen hinzugefügt:
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 { ... }
keepnames-Regeln verwenden
Sie können der Datei proguard-rules.pro auch keepnames-Regeln hinzufügen, wie im folgenden Beispiel gezeigt:
proguard-rules.pro
...
-keepnames class com.path.to.your.ParcelableArg
-keepnames class com.path.to.your.SerializableArg
-keepnames class com.path.to.your.EnumArg
...
Zusätzliche Ressourcen
Weitere Informationen zur Navigation finden Sie in den folgenden zusätzlichen Ressourcen.