העברת נתונים בין יעדים

הניווט מאפשר לכם לצרף נתונים לפעולת ניווט על ידי הגדרת ארגומנטים ליעד. לדוגמה, יעד של פרופיל משתמש יכול לקבל ארגומנט של מזהה משתמש כדי לקבוע איזה משתמש להציג.

באופן כללי, מומלץ מאוד להעביר רק את כמות הנתונים המינימלית בין היעדים. לדוגמה, צריך להעביר מפתח כדי לאחזר אובייקט במקום להעביר את האובייקט עצמו, כי השטח הכולל לכל המצבים השמורים מוגבל ב-Android. אם אתם צריכים להעביר כמויות גדולות של נתונים, השתמשו ב-ViewModel, כפי שמתואר בסקירה הכללית של ViewModel.

הגדרת ארגומנטים של יעדים

כדי להעביר נתונים בין יעדים, קודם צריך להגדיר את הארגומנט על ידי הוספה שלו ליעד שמקבל אותו, לפי השלבים הבאים:

  1. ב-Navigation Editor, לוחצים על היעד שמקבל את הארגומנט.
  2. בחלונית מאפיינים, לוחצים על הוספה (+).
  3. בחלון Add Argument Link שמופיע, מזינים את שם הארגומנט, סוג הארגומנט, אם הארגומנט יכול להיות null וערך ברירת מחדל, אם צריך.
  4. לוחצים על הוספה. שימו לב שהארגומנט מופיע עכשיו ברשימה Arguments בחלונית Attributes.
  5. אחר כך לוחצים על הפעולה הרלוונטית שמובילה ליעד הזה. בחלונית Attributes, הארגומנט החדש שהוספתם אמור להופיע בקטע Argument Default Values.
  6. אפשר גם לראות שהארגומנט נוסף ב-XML. לוחצים על הכרטיסייה Text כדי לעבור לתצוגת XML, ומוודאים שהארגומנט נוסף ליעד שמקבל את הארגומנט. לדוגמה:

     <fragment android:id="@+id/myFragment" >
         <argument
             android:name="myArg"
             app:argType="integer"
             android:defaultValue="0" />
     </fragment>
    

סוגי הארגומנטים הנתמכים

ספריית הניווט תומכת בסוגי הארגומנטים הבאים:

סוג תחביר app:argType תמיכה בערכי ברירת מחדל מטופל על ידי מסלולים ניתן להגדרה כ-null
מספר שלם app:argType="integer" כן כן לא
Float app:argType="float" כן כן לא
ארוך app:argType="long" כן – ערכי ברירת המחדל חייבים תמיד להסתיים בסיומת "L" (למשל, "123L"). כן לא
בוליאני app:argType="boolean" כן – "true" או "false" כן לא
מחרוזת app:argType="string" כן כן כן
הפניה למשאבים app:argType="reference" כן – ערכי ברירת המחדל חייבים להיות בפורמט "‎@resourceType/resourceName" (למשל "‎@style/myCustomStyle") או "0" כן לא
Custom Parcelable app:argType="<type>", כאשר <type> הוא שם המחלקה המלא של Parcelable תומך בערך ברירת המחדל "‎@null". לא תומך בערכי ברירת מחדל אחרים. לא כן
Custom Serializable app:argType="<type>", כאשר <type> הוא שם המחלקה המלא של Serializable תומך בערך ברירת המחדל "‎@null". לא תומך בערכי ברירת מחדל אחרים. לא כן
טיפוס בן מנייה (enum) בהתאמה אישית app:argType="<type>", כאשר <type> הוא השם המלא של ה-enum כן – ערכי ברירת המחדל חייבים להתאים לשם הלא מוגדר (למשל, "SUCCESS" כדי להתאים ל-MyEnum.SUCCESS). לא לא

אם סוג הארגומנט תומך בערכי null, אפשר להצהיר על ערך ברירת מחדל של null באמצעות android:defaultValue="@null".

אפשר לנתח מסלולים, קישורי עומק ומזהי URI עם הארגומנטים שלהם ממחרוזות. אי אפשר לעשות את זה באמצעות סוגי נתונים בהתאמה אישית כמו Parcelables ו-Serializables, כפי שמוצג בטבלה שלמעלה. כדי להעביר נתונים מורכבים בהתאמה אישית, צריך לאחסן את הנתונים במקום אחר, כמו ViewModel או מסד נתונים, ולהעביר רק מזהה בזמן הניווט. לאחר מכן, צריך לאחזר את הנתונים במיקום החדש אחרי שהניווט מסתיים.

כשבוחרים באחד מהסוגים בהתאמה אישית, מופיעה תיבת הדו-שיח Select Class וצריך לבחור את המחלקה שמתאימה לסוג הזה. בכרטיסייה Project אפשר לבחור מחלקה מהפרויקט הנוכחי.

אתם יכולים לבחור באפשרות <inferred type> כדי שספריית הניווט תקבע את הסוג על סמך הערך שסופק.

אפשר לבחור באפשרות מערך כדי לציין שהארגומנט צריך להיות מערך של ערך הסוג שנבחר. שימו לב לנקודות הבאות:

  • אין תמיכה במערכים של טיפוסי enum ובמערכים של הפניות למשאבים.
  • מערכים תומכים בערכים שניתנים לאיפוס, בלי קשר לתמיכה בערכים שניתנים לאיפוס של הסוג הבסיסי. לדוגמה, שימוש ב-app:argType="integer[]" מאפשר לכם להשתמש ב-app:nullable="true" כדי לציין שאפשר להעביר מערך null.
  • מערכים תומכים בערך ברירת מחדל יחיד, "‎@null". מערכים לא תומכים בערכי ברירת מחדל אחרים.

שינוי של ארגומנט יעד בפעולה

כל הפעולות שמנווטות ליעד משתמשות בארגומנטים ובערכי ברירת המחדל ברמת היעד. אם צריך, אפשר לשנות את ערך ברירת המחדל של ארגומנט (או להגדיר ערך אם הוא לא קיים) על ידי הגדרת ארגומנט ברמת הפעולה. הארגומנט הזה חייב להיות בעל אותו שם וסוג כמו הארגומנט שהוצהר ביעד.

ה-XML הבא מצהיר על פעולה עם ארגומנט שמחליף את הארגומנט ברמת היעד מהדוגמה הקודמת:

<action android:id="@+id/startMyFragment"
    app:destination="@+id/myFragment">
    <argument
        android:name="myArg"
        app:argType="integer"
        android:defaultValue="1" />
</action>

שימוש ב-Safe Args כדי להעביר נתונים עם מניעת שגיאות הקלדה

לרכיב הניווט יש פלאגין של Gradle שנקרא Safe Args, שיוצר אובייקט פשוט ומחלקות של בונים (builders) לניווט עם מניעת שגיאות הקלדה ולגישה לכל הארגומנטים המשויכים. מומלץ מאוד להשתמש ב-Safe Args כדי לנווט ולהעביר נתונים, כי הוא מונע שגיאות הקלדה.

אם אתם לא משתמשים ב-Gradle, אתם לא יכולים להשתמש בפלאגין Safe Args. במקרים כאלה, אפשר להשתמש ב-Bundles כדי להעביר נתונים ישירות.

כדי להוסיף את Safe Args לפרויקט, מוסיפים את classpath הבא לקובץ build.gradle ברמה העליונה:

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")
    }
}

בנוסף, צריך להחיל אחד משני התוספים הזמינים.

כדי ליצור קוד בשפת Java שמתאים למודולים של Java או למודולים משולבים של Java ו-Kotlin, מוסיפים את השורה הזו לקובץ build.gradle של האפליקציה או המודול:

Groovy

plugins {
  id 'androidx.navigation.safeargs'
}

Kotlin

plugins {
    id("androidx.navigation.safeargs")
}

לחלופין, כדי ליצור קוד Kotlin שמתאים למודולים של Kotlin בלבד, מוסיפים:

Groovy

plugins {
  id 'androidx.navigation.safeargs.kotlin'
}

Kotlin

plugins {
    id("androidx.navigation.safeargs.kotlin")
}

צריך להוסיף את android.useAndroidX=true לקובץ gradle.properties בהתאם להוראות במאמר מעבר ל-AndroidX.

אחרי שמפעילים את Safe Args, הקוד שנוצר מכיל את המחלקות והשיטות הבאות למניעת שגיאות הקלדה לכל פעולה, וגם לכל יעד שליחה וקבלה.

  • המערכת יוצרת מחלקה לכל יעד שממנו מגיעה פעולה. השם של המחלקה הזו הוא השם של יעד המוצא, בתוספת המילה Directions. לדוגמה, אם יעד המקור הוא מקטע בשם SpecifyAmountFragment, המחלקה שנוצרת נקראת SpecifyAmountFragmentDirections.

    במחלקה הזו יש שיטה לכל פעולה שמוגדרת ביעד המקורי.

  • לכל פעולה שמשמשת להעברת הארגומנט, נוצרת מחלקה פנימית שהשם שלה מבוסס על הפעולה. לדוגמה, אם הפעולה נקראת confirmationAction,, המחלקה נקראת ConfirmationAction. אם הפעולה מכילה ארגומנטים בלי defaultValue, משתמשים במחלקת הפעולה המשויכת כדי להגדיר את הערך של הארגומנטים.

  • נוצרת כיתה ביעד שאליו מעבירים את הבעלות. השם של המחלקה הזו הוא השם של היעד, בתוספת המילה Args. לדוגמה, אם שם הפרגמנט של היעד הוא ConfirmationFragment,, שם המחלקה שנוצרת הוא ConfirmationFragmentArgs. כדי לאחזר את הארגומנטים, משתמשים ב-method fromBundle() של המחלקה הזו.

בדוגמה הבאה אפשר לראות איך משתמשים בשיטות האלה כדי להגדיר ארגומנט ולהעביר אותו ל-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);
}

בקוד של יעד הקבלה, משתמשים ב-method‏ getArguments() כדי לאחזר את החבילה ולהשתמש בתוכן שלה. כשמשתמשים ביחסי התלות של -ktx, משתמשי Kotlin יכולים גם להשתמש בנציג המאפיין by navArgs() כדי לגשת לארגומנטים.

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 עם פעולה גלובלית

כשמשתמשים ב-Safe Args עם פעולה גלובלית, צריך לספק ערך android:id לרכיב הבסיס <navigation>, כמו שמוצג בדוגמה הבאה:

<?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 יוצר מחלקה מסוג Directions לרכיב <navigation> שמבוססת על הערך של android:id. לדוגמה, אם יש לכם רכיב <navigation> עם android:id=@+id/main_nav, המחלקה שנוצרת נקראת MainNavDirections. לכל היעדים בתוך הרכיב <navigation> יש שיטות שנוצרו כדי לגשת לכל הפעולות הגלובליות המשויכות באמצעות אותן שיטות שמתוארות בסעיף הקודם.

העברת נתונים בין יעדים באמצעות אובייקטים מסוג Bundle

אם אתם לא משתמשים ב-Gradle, אתם עדיין יכולים להעביר ארגומנטים בין יעדים באמצעות אובייקטים מסוג Bundle. יוצרים אובייקט Bundle ומעבירים אותו ליעד באמצעות navigate(), כמו בדוגמה הבאה:

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);

בקוד של היעד שמקבל את הנתונים, משתמשים ב-method‏ getArguments() כדי לאחזר את Bundle ולהשתמש בתוכן שלו:

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"));

העברת נתונים ליעד ההתחלה

אתם יכולים להעביר נתונים ליעד ההתחלה של האפליקציה. קודם כל, צריך ליצור באופן מפורש Bundle שמכיל את הנתונים. בשלב הבא, משתמשים באחת מהשיטות הבאות כדי להעביר את הערך של Bundle ליעד ההתחלה:

כדי לאחזר את הנתונים ביעד ההתחלה, מפעילים את Fragment.getArguments().

שיקולים לגבי ProGuard

אם אתם מכווצים את הקוד, אתם צריכים למנוע את ערפול השמות של המחלקות Parcelable,‏ Serializable ו-Enum כחלק מתהליך המזעור. אפשר לעשות זאת באחת משתי הדרכים הבאות:

  • משתמשים בהערות של ‎ @Keep.
  • משתמשים בכללי keepnames.

בסעיפי המשנה הבאים מתוארות הגישות האלה.

שימוש בהערות ב-‎ @Keep

בדוגמה הבאה מוסיפים הערות @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 { ... }

שימוש בכללי keepnames

אפשר גם להוסיף כללי keepnames לקובץ proguard-rules.pro, כמו בדוגמה הבאה:

proguard-rules.pro

...

-keepnames class com.path.to.your.ParcelableArg
-keepnames class com.path.to.your.SerializableArg
-keepnames class com.path.to.your.EnumArg

...

מקורות מידע נוספים

למידע נוסף על ניווט, אפשר לעיין במקורות המידע הבאים.

סרטונים