Nawigacja umożliwia dołączanie danych do operacji nawigacji przez definiowanie argumentów dla miejsca docelowego. Na przykład miejsce docelowe profilu użytkownika może przyjmować argument identyfikatora użytkownika, aby określić, którego użytkownika wyświetlić.
Ogólnie zalecamy przekazywanie między miejscami docelowymi tylko minimalnej ilości danych. Na przykład należy przekazać klucz, aby pobrać obiekt, zamiast przekazywać sam obiekt, ponieważ łączna ilość miejsca na wszystkie zapisane stany jest ograniczona na Androidzie. Jeśli chcesz przekazać duże ilości danych, użyj ViewModel zgodnie z opisem w artykule Omówienie ViewModel.
Definiowanie argumentów miejsca docelowego
Aby przekazywać dane między miejscami docelowymi, najpierw zdefiniuj argument, dodając go do miejsca docelowego, które go otrzymuje. Aby to zrobić, wykonaj te czynności:
- W edytorze nawigacji kliknij miejsce docelowe, które otrzymuje argument.
- W panelu Atrybuty kliknij Dodaj (+).
- W oknie Dodaj link argumentu, które się pojawi, wpisz nazwę argumentu, typ argumentu, określ, czy argument może mieć wartość null, i w razie potrzeby podaj wartość domyślną.
- Kliknij Dodaj. Zauważ, że argument pojawia się teraz na liście Argumenty w panelu Atrybuty.
- Następnie kliknij odpowiednie działanie, które prowadzi do tego miejsca docelowego. W panelu Atrybuty w sekcji Wartości domyślne argumentów powinien być teraz widoczny nowo dodany argument.
Możesz też zobaczyć, że argument został dodany w kodzie XML. Kliknij kartę Tekst, aby przełączyć się na widok XML, i zwróć uwagę, że argument został dodany do miejsca docelowego, które go otrzymuje. Oto przykład:
<fragment android:id="@+id/myFragment" > <argument android:name="myArg" app:argType="integer" android:defaultValue="0" /> </fragment>
Obsługiwane typy argumentów
Biblioteka nawigacji obsługuje te typy argumentów:
| Typ | Składnia app:argType | Obsługa wartości domyślnych | Obsługiwane przez trasy | Dopuszczalna wartość null |
|---|---|---|---|---|
| Liczba całkowita | app:argType="integer" | Tak | Tak | Nie |
| Liczba zmiennoprzecinkowa | app:argType="float" | Tak | Tak | Nie |
| Długi | app:argType="long" | Tak – wartości domyślne muszą zawsze kończyć się sufiksem „L” (np. „123L”). | Tak | Nie |
| Wartość logiczna | app:argType="boolean" | Tak – „true” lub „false” | Tak | Nie |
| Ciąg znaków | app:argType="string" | Tak | Tak | Tak |
| Odniesienie do zasobu | app:argType="reference" | Tak – wartości domyślne muszą mieć format „@resourceType/resourceName” (np. „@style/myCustomStyle”) lub „0” | Tak | Nie |
| Niestandardowy obiekt Parcelable | app:argType="<type>", gdzie <type> to pełna i jednoznaczna nazwa klasy Parcelable |
Obsługuje wartość domyślną „@null”. Nie obsługuje innych wartości domyślnych. | Nie | Tak |
| Niestandardowy serializowalny | app:argType="<type>", gdzie <type> to pełna i jednoznaczna nazwa klasy Serializable |
Obsługuje wartość domyślną „@null”. Nie obsługuje innych wartości domyślnych. | Nie | Tak |
| Niestandardowy typ wyliczeniowy | app:argType="<type>", gdzie <type> to pełna i jednoznaczna nazwa typu wyliczeniowego. | Tak – wartości domyślne muszą być zgodne z nazwą niekwalifikowaną (np. „SUCCESS” musi pasować do MyEnum.SUCCESS). | Nie | Nie |
Jeśli typ argumentu obsługuje wartości null, możesz zadeklarować domyślną wartość null, używając android:defaultValue="@null".
Trasy, precyzyjne linki i identyfikatory URI z argumentami można analizować z ciągów znaków. Nie jest to możliwe w przypadku niestandardowych typów danych, takich jak Parcelable i Serializable, jak pokazano w tabeli powyżej. Aby przekazywać niestandardowe dane złożone, przechowuj je w innym magazynie danych, np. w ViewModel lub bazie danych, i podczas nawigacji przekazuj tylko identyfikator. Następnie pobierz dane w nowej lokalizacji po zakończeniu nawigacji.
Gdy wybierzesz jeden z typów niestandardowych, pojawi się okno Wybierz klasę, w którym musisz wybrać odpowiednią klasę dla tego typu. Karta Projekt umożliwia wybranie zajęć z bieżącego projektu.
Możesz wybrać <inferred type>, aby biblioteka nawigacji określiła typ na podstawie podanej wartości.
Możesz wybrać Tablica, aby wskazać, że argument powinien być tablicą wybranej wartości Typ. Uwaga:
- Tablice typów wyliczeniowych i tablice odwołań do zasobów nie są obsługiwane.
- Tablice obsługują wartości z możliwością wartości null, niezależnie od obsługi wartości z możliwością wartości null typu podstawowego. Na przykład użycie
app:argType="integer[]"pozwala użyćapp:nullable="true", aby wskazać, że przekazanie tablicy o wartości null jest dopuszczalne. - Tablice obsługują jedną wartość domyślną, „@null”. Tablice nie obsługują żadnej innej wartości domyślnej.
Zastępowanie argumentu miejsca docelowego w działaniu
Argumenty na poziomie miejsca docelowego i wartości domyślne są używane przez wszystkie działania, które prowadzą do miejsca docelowego. W razie potrzeby możesz zastąpić domyślną wartość argumentu (lub ustawić ją, jeśli jeszcze nie istnieje), definiując argument na poziomie działania. Ten argument musi mieć taką samą nazwę i typ jak argument zadeklarowany w miejscu docelowym.
Poniższy kod XML deklaruje działanie z argumentem, który zastępuje argument na poziomie miejsca docelowego z poprzedniego przykładu:
<action android:id="@+id/startMyFragment"
app:destination="@+id/myFragment">
<argument
android:name="myArg"
app:argType="integer"
android:defaultValue="1" />
</action>
Przekazywanie danych z zabezpieczeniami wpisywania za pomocą Safe Args
Komponent nawigacji zawiera wtyczkę Gradle o nazwie Safe Args, która generuje proste klasy obiektów i konstruktorów, aby zapewnić bezpieczną nawigację i dostęp do powiązanych argumentów. Zdecydowanie zalecamy używanie Safe Args do nawigacji i przekazywania danych, ponieważ zapewnia to zabezpieczenia wpisywania.
Jeśli nie używasz Gradle, nie możesz korzystać z wtyczki Safe Args. W takich przypadkach możesz użyć pakietów, aby bezpośrednio przekazywać dane.
Aby dodać do projektu Safe Args, w pliku najwyższego poziomu build.gradle umieść ten kod:classpath
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") } }
Musisz też zastosować jedną z 2 dostępnych wtyczek.
Aby wygenerować kod w języku Java odpowiedni dla modułów Java lub mieszanych modułów Java i Kotlin, dodaj ten wiersz do pliku build.gradle aplikacji lub modułu:
Groovy
plugins { id 'androidx.navigation.safeargs' }
Kotlin
plugins { id("androidx.navigation.safeargs") }
Aby wygenerować kod w języku Kotlin odpowiedni dla modułów tylko w tym języku, dodaj:
Groovy
plugins { id 'androidx.navigation.safeargs.kotlin' }
Kotlin
plugins { id("androidx.navigation.safeargs.kotlin") }
W pliku gradle.properties musisz mieć android.useAndroidX=true zgodnie z informacjami w artykule Migracja do AndroidaX.
Po włączeniu Safe Args wygenerowany kod zawiera te klasy i metody zabezpieczeń wpisywania dla każdego działania, a także dla każdego miejsca docelowego wysyłania i odbierania.
Dla każdego miejsca docelowego, z którego pochodzi działanie, tworzona jest klasa. Nazwa tej klasy to nazwa miejsca docelowego z dodatkiem słowa „Directions”. Jeśli na przykład miejscem docelowym jest fragment o nazwie
SpecifyAmountFragment, wygenerowana klasa będzie miała nazwęSpecifyAmountFragmentDirections.Ta klasa ma metodę dla każdego działania zdefiniowanego w miejscu docelowym, z którego pochodzi.
Dla każdego działania używanego do przekazywania argumentu tworzona jest klasa wewnętrzna, której nazwa jest oparta na działaniu. Jeśli na przykład działanie nazywa się
confirmationAction,, klasa ma nazwęConfirmationAction. Jeśli działanie zawiera argumenty bezdefaultValue, do ustawienia wartości argumentów używasz powiązanej klasy działania.Tworzona jest klasa dla miejsca docelowego. Nazwa tej klasy to nazwa miejsca docelowego z dodatkiem „Args”. Jeśli na przykład fragment docelowy ma nazwę
ConfirmationFragment,, wygenerowana klasa będzie miała nazwęConfirmationFragmentArgs. Aby pobrać argumenty, użyj metodyfromBundle()tej klasy.
Z poniższego przykładu dowiesz się, jak używać tych metod do ustawiania argumentu i przekazywania go do metody 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);
}
W kodzie miejsca docelowego użyj metody getArguments(), aby pobrać pakiet i użyć jego zawartości. Jeśli używasz zależności -ktx, użytkownicy Kotlina mogą też używać delegata właściwości by navArgs(), aby uzyskać dostęp do argumentów.
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 + "");
}
Używanie Safe Args z działaniem globalnym
Jeśli używasz Safe Args z działaniem globalnym, musisz podać wartość android:id dla elementu głównego <navigation>, jak w tym przykładzie:
<?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>
Nawigacja generuje klasę Directions dla elementu <navigation> na podstawie wartości android:id. Jeśli na przykład masz element <navigation> z atrybutem android:id=@+id/main_nav, wygenerowana klasa będzie miała nazwę MainNavDirections. Wszystkie miejsca docelowe w elemencie <navigation> mają wygenerowane metody dostępu do wszystkich powiązanych działań globalnych przy użyciu tych samych metod, które opisano w poprzedniej sekcji.
Przekazywanie danych między miejscami docelowymi za pomocą obiektów Bundle
Jeśli nie używasz Gradle, możesz przekazywać argumenty między miejscami docelowymi za pomocą obiektów Bundle. Utwórz obiekt Bundle i przekaż go do miejsca docelowego za pomocą navigate(), jak w tym przykładzie:
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);
W kodzie miejsca docelowego użyj metody getArguments(), aby pobrać Bundle i użyć jego zawartości:
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"));
Przekazywanie danych do miejsca docelowego
Możesz przekazywać dane do miejsca docelowego, od którego zaczyna się aplikacja. Najpierw musisz jawnie utworzyć obiekt Bundle, który będzie przechowywać dane. Następnie użyj jednej z tych metod, aby przekazać Bundle do miejsca docelowego:
- Jeśli tworzysz
NavHostautomatycznie, wywołajNavHostFragment.create(R.navigation.graph, args), gdzieargstoBundlezawierający Twoje dane. - W przeciwnym razie możesz ustawić argumenty miejsca docelowego, wywołując jedno z tych przeciążeń funkcji
NavController.setGraph():- Użyj identyfikatora wykresu:
navController.setGraph(R.navigation.graph, args) - Użyj samego wykresu:
navController.setGraph(navGraph, args)
- Użyj identyfikatora wykresu:
Aby pobrać dane w miejscu docelowym, wywołaj Fragment.getArguments().
Uwagi dotyczące ProGuard
Jeśli zmniejszasz kod, musisz zapobiec zaciemnianiu nazw klas Parcelable, Serializable i Enum w ramach procesu minifikacji. Można to zrobić na 2 sposoby:
- Używaj adnotacji @Keep.
- Użyj reguł keepnames.
W kolejnych sekcjach opisujemy te podejścia.
Używanie adnotacji @Keep
W tym przykładzie do definicji klas modelu dodano adnotacje @Keep:
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 { ... }
Używanie reguł keepnames
Możesz też dodać reguły keepnames do pliku proguard-rules.pro, jak pokazano w tym przykładzie:
proguard-rules.pro
...
-keepnames class com.path.to.your.ParcelableArg
-keepnames class com.path.to.your.SerializableArg
-keepnames class com.path.to.your.EnumArg
...
Dodatkowe materiały
Więcej informacji o nawigacji znajdziesz w tych materiałach: