החלת לוגיקה או עטיפות על יעדים

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

יצירת מעצב בהתאמה אישית

כדי ליצור דקורטור, מרחיבים את המחלקה NavEntryDecorator ומבטלים את השיטות הבאות:

• decorate – פונקציית lambda קומפוזבילית שמופעלת עבור כל NavEntry במקבץ פעילויות קודמות (back stack). היא מקבלת את NavEntry כפרמטר. כך אפשר ליצור אובייקטים של מצב שמקושרים לערך של contentKey של הרשומה. אפשר להשתמש ב-CompositionLocalProvider כדי לספק תלויות לתוכן של הרשומה. אפשר גם להקיף את התוכן בפונקציה קומפוזבילית, או להפעיל תופעות לוואי. תמיד צריך להפעיל את entry.Content() בתוך ה-method הזה.
• ‫onPop – קריאה חוזרת (callback) שמופעלת כש-NavEntry הוסר ממקבץ הפעילויות הקודמות (back stack) ויצא מהקומפוזיציה. הוא מקבל את contentKey של הרשומה שהוסרה. משתמשים ב-contentKey כדי לזהות ולנקות כל מצב שמשויך לרשומה הזו.

בדוגמה הבאה מורחבת המחלקה NavEntryDecorator כדי ליצור דקורטור בהתאמה אישית.

// import androidx.navigation3.runtime.NavEntryDecorator
class CustomNavEntryDecorator<T : Any> : NavEntryDecorator<T>(
    decorate = { entry ->
        Log.d("CustomNavEntryDecorator", "entry with ${entry.contentKey} entered composition and was decorated")
        entry.Content()
    },
    onPop = { contentKey -> Log.d("CustomNavEntryDecorator", "entry with $contentKey was popped") }
)
DecoratorSnippets.kt

אם הדקורטור צריך גישה למצב, יוצרים פונקציה הניתנת להגדרה שיוצרת את המצב הזה, ואז משתמשים בה כדי ליצור את הדקורטור. דוגמה להטמעה מופיעה בקוד המקור של rememberSaveableStateHolderNavEntryDecorator. הפעולה הזו יוצרת את הסטטוס – SaveableStateHolder – ומשתמשת בו כדי ליצור את ה-decorator.

עיצוב מקבץ פעילויות קודמות

אחרי שיוצרים את NavEntryDecorator, אפשר להוסיף עיצוב לרשומות במקבץ פעילויות קודמות (back stack) באחת משתי דרכים:

• שימוש ב-rememberDecoratedNavEntries. הפונקציה הזו שימושית כשמשתמשים בכמה מחסניות של פעולות קודמות, שלכל אחת מהן יש קבוצה משלה של מעצבים (פרטים נוספים זמינים במתכון הקוד הזה). הפונקציה מחזירה רשימה מעוצבת של NavEntry שאפשר להשתמש בה עם NavDisplay.
• מעבירים את ה-decorator ישירות אל NavDisplay באמצעות הפרמטר entryDecorators. ‫NavDisplay calls rememberDecoratedNavEntries מתבצעת מתחת לפני השטח, והערכים המעוטרים מוצגים.

הכללת מעצב ברירת המחדל

‫Navigation 3 כולל מעצב ברירת מחדל בשם SaveableStateHolderNavEntryDecorator שמאפשר לשמור את הסטטוס של NavEntry גם אחרי שינויים בהגדרות וגם אחרי שהתהליך מסתיים. הוא עוטף את התוכן של NavEntry ב-SaveableStateProvider, וכך מאפשר לקריאות של rememberSaveable בתוך התוכן של NavEntry לפעול בצורה תקינה.

אלא אם המחלקה לקישוט מספקת SaveableStateProvider, צריך לכלול את SaveableStateHolderNavEntryDecorator כמחלקה הראשונה לקישוט ברשימה של המחלקות לקישוט שסופקו. הוא נוצר באמצעות rememberSaveableStateHolderNavEntryDecorator.

לדוגמה:

// import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
NavDisplay(
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        remember { CustomNavEntryDecorator() }
    ),
    // ...
)
DecoratorSnippets.kt

העברת תוצאות באמצעות ResultEventBusNavEntryDecorator

החל מגרסה 3 1.2.0 של Navigation, אפשר להשתמש ב-ResultEventBusNavEntryDecorator כדי לספק ResultEventBus לכל NavEntry באמצעות LocalResultEventBus composition local.

כברירת מחדל, rememberResultEventBusNavEntryDecorator יוצר וזוכר מופע ResultEventBus משלו באופן פנימי באמצעות rememberResultEventBus. אם אתם צריכים לגשת ל-event bus מחוץ להיררכיית ה-decorator (למשל, בפיגום של האפליקציה ברמה העליונה), אתם יכולים להעביר את ResultEventBus על ידי קריאה ל-rememberResultEventBus והעברה שלו ל-rememberResultEventBusNavEntryDecorator(resultEventBus):

val resultEventBus = rememberResultEventBus()

NavDisplay(
    /* ... */
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        rememberResultEventBusNavEntryDecorator(resultEventBus = resultEventBus)
    )
)
DecoratorSnippets.kt

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

מתי כדאי להשתמש ב-decorator

אפשר להשתמש ב-decorator כדי:

• יוצרים תלות לכל NavEntry במקבץ פעילויות קודמות (back stack). לדוגמה, הפונקציה ViewModelStoreNavEntryDecorator יוצרת ViewModelStore לכל NavEntry.
• העברת תוצאות ותקשורת בין יעדים. לדוגמה, ResultEventBusNavEntryDecorator מספק ResultEventBus ליעדים במקבץ פעילויות קודמות (back stack).
• הגדרת היקף של אובייקט לכמה NavEntry. לדוגמה, כדי לשתף ViewModel בין כמה רשומות.
• ביצוע אותה פעולה בכמה NavEntry. לדוגמה, כדי לבצע פעולות של רישום ביומן, ניפוי באגים או מעקב עבור כל רשומה.
• עוטפים את NavEntrys באותה פונקציה קומפוזבילית.
• ניקוי המצב שמשויך ל-NavEntry. לדוגמה, כשערך מוסר ממקבץ הפעילויות הקודמות (back stack), ViewModelStoreNavEntryDecorator מנקה את ViewModelStore המשויך.

אין להשתמש ב-Decorator כדי:

• העברת תלות ל-NavEntry יחיד.
• מספקים יחסי תלות שההיקף שלהם רחב יותר מזה של מקבץ פעילויות קודמות (back stack).

בשני המקרים האלה, צריך להעביר את התלות ישירות כשיוצרים את NavEntry במקום זאת.

דוגמאות קוד נוספות זמינות במאמר NavEntryDecorator.