ביצוע אינטראקציה פרוגרמטית עם רכיב הניווט

רכיב הניווט מספק דרכים ליצור רכיבי ניווט מסוימים ולקיים איתם אינטראקציה באופן פרוגרמטי.

יצירת NavHostFragment

אתם יכולים להשתמש ב-NavHostFragment.create() כדי ליצור באופן פרוגרמטי NavHostFragment עם משאב תרשים ספציפי, כמו בדוגמה הבאה:

Kotlin

val finalHost = NavHostFragment.create(R.navigation.example_graph)
supportFragmentManager.beginTransaction()
    .replace(R.id.nav_host, finalHost)
    .setPrimaryNavigationFragment(finalHost) // equivalent to app:defaultNavHost="true"
    .commit()

Java

NavHostFragment finalHost = NavHostFragment.create(R.navigation.example_graph);
getSupportFragmentManager().beginTransaction()
    .replace(R.id.nav_host, finalHost)
    .setPrimaryNavigationFragment(finalHost) // equivalent to app:defaultNavHost="true"
    .commit();

חשוב לזכור ש-setPrimaryNavigationFragment(finalHost) מאפשר ל-NavHost ליירט לחיצות על הכפתור "הקודם" במערכת. אפשר גם להטמיע את ההתנהגות הזו ב-XML של NavHost על ידי הוספת app:defaultNavHost="true". אם אתם מטמיעים התנהגות מותאמת אישית של הכפתור "הקודם" ולא רוצים שה-NavHost יקלוט את הלחיצות על הכפתור "הקודם", אתם יכולים להעביר את null אל setPrimaryNavigationFragment().

החל מגרסה 2.2.0 של Navigation, אפשר לקבל הפניה ל-NavBackStackEntry לכל יעד במחסנית הניווט על ידי קריאה ל-NavController.getBackStackEntry() והעברת מזהה יעד. אם מקבץ הפעילויות הקודמות מכיל יותר ממופע אחד של היעד שצוין, הפונקציה getBackStackEntry() מחזירה את המופע העליון ביותר מהמקבץ.

האובייקט NavBackStackEntry שמוחזר מספק את האובייקטים הבאים ברמת היעד:

האובייקטים האלה תקפים למשך כל משך החיים של היעד במקבץ הפעילויות הקודמות (back stack). כשמסירים את היעד המשויך ממקבץ הפעילויות הקודמות, ה-Lifecycle מושמד, המצב לא נשמר יותר וכל האובייקטים של ViewModel נמחקים.

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

זה שימושי במיוחד כשעובדים עם סוגי יעדים שלא משויך אליהם Lifecycle באופן אוטומטי, כמו יעדים בהתאמה אישית.

לדוגמה, אפשר לצפות ב-Lifecycle של NavBackStackEntry בדיוק כמו שצופים ב-Lifecycle של מקטע או פעילות. בנוסף, NavBackStackEntry הוא LifecycleOwner, כלומר אפשר להשתמש בו כשצופים ב-LiveData או עם רכיבים אחרים שמודעים למחזור החיים, כמו בדוגמה הבאה:

Kotlin

myViewModel.liveData.observe(backStackEntry, Observer { myData ->
    // react to live data update
})

Java

myViewModel.getLiveData().observe(backStackEntry, myData -> {
    // react to live data update
});

מצב מחזור החיים מתעדכן באופן אוטומטי בכל פעם שמתבצעת קריאה ל-navigate(). מצבי מחזור החיים של יעדים שלא נמצאים בחלק העליון של מקבץ הפעילויות הקודמות (back stack) עוברים מ-RESUMED ל-STARTED אם היעדים עדיין גלויים מתחת ליעד FloatingWindow, כמו יעד של תיבת דו-שיח, או ל-STOPPED במקרים אחרים.

החזרת תוצאה ליעד הקודם

ב-Navigation מגרסה 2.3 ואילך, NavBackStackEntry נותן גישה אל SavedStateHandle. ‫SavedStateHandle הוא מפה של מפתח/ערך שאפשר להשתמש בה כדי לאחסן ולשלוף נתונים. הערכים האלה נשמרים גם אחרי השבתת התהליך, כולל שינויים בהגדרות, והם זמינים דרך אותו אובייקט. באמצעות SavedStateHandle, אתם יכולים לגשת לנתונים ולהעביר אותם בין יעדים. זה שימושי במיוחד כמנגנון לקבלת נתונים בחזרה מיעד אחרי שהוא נשלף מהמחסנית.

כדי להעביר נתונים בחזרה ליעד א' מיעד ב', קודם צריך להגדיר את יעד א' כך שיאזין לתוצאה ב-SavedStateHandle שלו. כדי לעשות את זה, מאחזרים את NavBackStackEntry באמצעות ה-API של getCurrentBackStackEntry() ואז observe את LiveData שסופק על ידי SavedStateHandle.

Kotlin

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    val navController = findNavController();
    // We use a String here, but any type that can be put in a Bundle is supported
    navController.currentBackStackEntry?.savedStateHandle?.getLiveData<String>("key")?.observe(
        viewLifecycleOwner) { result ->
        // Do something with the result.
    }
}

Java

@Override
public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
    NavController navController = NavHostFragment.findNavController(this);
    // We use a String here, but any type that can be put in a Bundle is supported
    MutableLiveData<String> liveData = navController.getCurrentBackStackEntry()
            .getSavedStateHandle()
            .getLiveData("key");
    liveData.observe(getViewLifecycleOwner(), new Observer<String>() {
        @Override
        public void onChanged(String s) {
            // Do something with the result.
        }
    });
}

ביעד ב', צריך set את התוצאה בSavedStateHandle של יעד א' באמצעות ה-API של getPreviousBackStackEntry().

Kotlin

navController.previousBackStackEntry?.savedStateHandle?.set("key", result)

Java

navController.getPreviousBackStackEntry().getSavedStateHandle().set("key", result);

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

שיקולים לשימוש ביעדי תיבות דו-שיח

כשnavigate ליעד שתופס את כל התצוגה של NavHost (כמו יעד <fragment>), מחזור החיים של היעד הקודם נעצר, ומונע קריאות חוזרות (callbacks) ל-LiveData שסופק על ידי SavedStateHandle.

עם זאת, כשמנווטים אל יעד של תיבת דו-שיח, היעד הקודם גם מוצג במסך ולכן הוא גם STARTED, למרות שהוא לא היעד הנוכחי. כלומר, קריאות ל-getCurrentBackStackEntry() מתוך שיטות של מחזור חיים כמו onViewCreated() יחזירו את ה-NavBackStackEntry של יעד תיבת הדו-שיח אחרי שינוי בהגדרות או השבתת תהליך ויצירה מחדש (כי תיבת הדו-שיח משוחזרת מעל היעד האחר). לכן, כדאי להשתמש ב-getBackStackEntry() עם המזהה של היעד כדי לוודא שאתם תמיד משתמשים ב-NavBackStackEntry הנכון.

זה גם אומר שכל Observer שתגדירו בתוצאה LiveData יופעל גם כשיעדי תיבת הדו-שיח עדיין מוצגים במסך. אם רוצים לבדוק את התוצאה רק כשתיבת הדו-שיח של היעד נסגרת והיעד הבסיסי הופך ליעד הנוכחי, אפשר לבחון את ה-Lifecycle שמשויך ל-NavBackStackEntry ולאחזר את התוצאה רק כשהיא הופכת ל-RESUMED.

Kotlin

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    val navController = findNavController();
    // After a configuration change or process death, the currentBackStackEntry
    // points to the dialog destination, so you must use getBackStackEntry()
    // with the specific ID of your destination to ensure we always
    // get the right NavBackStackEntry
    val navBackStackEntry = navController.getBackStackEntry(R.id.your_fragment)

    // Create our observer and add it to the NavBackStackEntry's lifecycle
    val observer = LifecycleEventObserver { _, event ->
        if (event == Lifecycle.Event.ON_RESUME
            && navBackStackEntry.savedStateHandle.contains("key")) {
            val result = navBackStackEntry.savedStateHandle.get<String>("key");
            // Do something with the result
        }
    }
    navBackStackEntry.lifecycle.addObserver(observer)

    // As addObserver() does not automatically remove the observer, we
    // call removeObserver() manually when the view lifecycle is destroyed
    viewLifecycleOwner.lifecycle.addObserver(LifecycleEventObserver { _, event ->
        if (event == Lifecycle.Event.ON_DESTROY) {
            navBackStackEntry.lifecycle.removeObserver(observer)
        }
    })
}

Java

@Override
public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
    super.onViewCreated(view, savedInstanceState);
    NavController navController = NavHostFragment.findNavController(this);
    // After a configuration change or process death, the currentBackStackEntry
    // points to the dialog destination, so you must use getBackStackEntry()
    // with the specific ID of your destination to ensure we always
    // get the right NavBackStackEntry
    final NavBackStackEntry navBackStackEntry = navController.getBackStackEntry(R.id.your_fragment);

    // Create our observer and add it to the NavBackStackEntry's lifecycle
    final LifecycleEventObserver observer = new LifecycleEventObserver() {
        @Override
        public void onStateChanged(@NonNull LifecycleOwner source, @NonNull Lifecycle.Event event) {
            if (event.equals(Lifecycle.Event.ON_RESUME)
                && navBackStackEntry.getSavedStateHandle().contains("key")) {
                String result = navBackStackEntry.getSavedStateHandle().get("key");
                // Do something with the result
            }
        }
    };
    navBackStackEntry.getLifecycle().addObserver(observer);

    // As addObserver() does not automatically remove the observer, we
    // call removeObserver() manually when the view lifecycle is destroyed
    getViewLifecycleOwner().getLifecycle().addObserver(new LifecycleEventObserver() {
        @Override
        public void onStateChanged(@NonNull LifecycleOwner source, @NonNull Lifecycle.Event event) {
            if (event.equals(Lifecycle.Event.ON_DESTROY)) {
                navBackStackEntry.getLifecycle().removeObserver(observer)
            }
        }
    });
}

מקבץ הפעילויות הקודמות (back stack) של Navigation שומר NavBackStackEntry לא רק לכל יעד בנפרד, אלא גם לכל תרשים ניווט ראשי שמכיל את היעד הנפרד. כך אפשר לאחזר NavBackStackEntry שמוגדרת להיקף של תרשים ניווט. ‫NavBackStackEntry ברמת תרשים הניווט מאפשר ליצור ViewModel ברמת תרשים הניווט, וכך לשתף נתונים שקשורים לממשק המשתמש בין היעדים בתרשים. כל אובייקט מסוג ViewModel שנוצר בדרך הזו נשאר עד שהאובייקטים המשויכים NavHost ו-ViewModelStore נמחקים, או עד שתרשים הניווט נשלף ממקבץ הפעילויות הקודמות (back stack).

בדוגמה הבאה אפשר לראות איך מאחזרים ViewModel שמוגדרת לו היקף של תרשים ניווט:

Kotlin

val viewModel: MyViewModel
        by navGraphViewModels(R.id.my_graph)

Java

NavBackStackEntry backStackEntry = navController.getBackStackEntry(R.id.my_graph);
MyViewModel viewModel = new ViewModelProvider(backStackEntry).get(MyViewModel.class);

אם אתם משתמשים ב-Navigation בגרסה 2.2.0 או בגרסה קודמת, אתם צריכים לספק מפעל משלכם כדי להשתמש ב-Saved State עם ViewModels, כמו שמוצג בדוגמה הבאה:

Kotlin

val viewModel: MyViewModel by navGraphViewModels(R.id.my_graph) {
    SavedStateViewModelFactory(requireActivity().application, requireParentFragment())
}

Java

NavBackStackEntry backStackEntry = navController.getBackStackEntry(R.id.my_graph);

ViewModelProvider viewModelProvider = new ViewModelProvider(
        backStackEntry.getViewModelStore(),
        new SavedStateViewModelFactory(
                requireActivity().getApplication(), requireParentFragment()));

MyViewModel myViewModel = provider.get(myViewModel.getClass());

מידע נוסף על ViewModel זמין במאמר סקירה כללית של ViewModel.

שינוי של תרשימי ניווט מנופחים

אפשר לשנות באופן דינמי תרשים ניווט מנופח בזמן הריצה.

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

כדאי להביא בחשבון את NavGraph:

<?xml version="1.0" encoding="utf-8"?>
<navigation xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/nav_graph"
    app:startDestination="@id/home">
    <fragment
        android:id="@+id/home"
        android:name="com.example.android.navigation.HomeFragment"
        android:label="fragment_home"
        tools:layout="@layout/fragment_home" />
    <fragment
        android:id="@+id/location"
        android:name="com.example.android.navigation.LocationFragment"
        android:label="fragment_location"
        tools:layout="@layout/fragment_location" />
    <fragment
        android:id="@+id/shop"
        android:name="com.example.android.navigation.ShopFragment"
        android:label="fragment_shop"
        tools:layout="@layout/fragment_shop" />
    <fragment
        android:id="@+id/settings"
        android:name="com.example.android.navigation.SettingsFragment"
        android:label="fragment_settings"
        tools:layout="@layout/fragment_settings" />
</navigation>

כשהתרשים הזה נטען, המאפיין app:startDestination מציין שצריך להציג את HomeFragment. כדי לשנות את יעד ההתחלה באופן דינמי:

  1. קודם כל, מנפחים את NavGraph באופן ידני.
  2. שינוי יעד ההתחלה.
  3. בסיום, מחברים ידנית את התרשים אל NavController.

Kotlin

val navHostFragment =
        supportFragmentManager.findFragmentById(R.id.nav_host_fragment) as NavHostFragment

val navController = navHostFragment.navController
val navGraph = navController.navInflater.inflate(R.navigation.bottom_nav_graph)
navGraph.startDestination = R.id.shop
navController.graph = navGraph
binding.bottomNavView.setupWithNavController(navController)

Java

NavHostFragment navHostFragment = (NavHostFragment) getSupportFragmentManager()
        .findFragmentById(R.id.nav_host_fragment);

NavController navController = navHostFragment.getNavController();
NavGraph navGraph = navController.getNavInflater().inflate(R.navigation.bottom_nav_graph);
navGraph.setStartDestination(R.id.shop);
navController.setGraph(navGraph);
NavigationUI.setupWithNavController(binding.bottomNavView, navController);

עכשיו, כשהאפליקציה מופעלת, מוצג ShopFragment במקום HomeFragment.

כשמשתמשים בקישורי עומק, NavController יוצר באופן אוטומטי מקבץ פעילויות קודמות (back stack) ליעד של קישור העומק. אם המשתמש מנווט לקישור העומק ואז מנווט אחורה, הוא יגיע ליעד ההתחלה בשלב כלשהו. אם משתמשים בשיטה מהדוגמה הקודמת כדי לשנות את יעד ההתחלה, יעד ההתחלה הנכון יתווסף למקבץ הפעילויות הקודמות שנוצר.

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