Przekazywanie danych między miejscami docelowymi

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:

  1. W edytorze nawigacji kliknij miejsce docelowe, które otrzymuje argument.
  2. W panelu Atrybuty kliknij Dodaj (+).
  3. 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ą.
  4. Kliknij Dodaj. Zauważ, że argument pojawia się teraz na liście Argumenty w panelu Atrybuty.
  5. 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.
  6. 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 bez defaultValue, 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 metody fromBundle() 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:

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:

Codelabs

Filmy