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

ב-Navigation 3, אתם משתמשים במטא-נתונים כדי לשתף מידע שרירותי בין רכיבי ספרייה שונים כמו NavEntry,‏ Scene ו-NavDisplay. ברמה הכי בסיסית, מטא-נתונים הם Map<String, Any>. עם זאת, הספרייה מספקת הפשטות נוספות כדי לפשט את הקריאה והכתיבה של מטא-נתונים ולמנוע שגיאות הקלדה.

לספק מטא-נתונים של NavEntry

אם האפליקציה יוצרת את המופעים של NavEntry באופן ישיר, אתם מספקים מטא-נתונים לרשומה באמצעות הפרמטר metadata של ה-constructor:

when (key) {
    is Home -> NavEntry(key, metadata = mapOf("key" to "value")) {}
}
MetadataSnippets.kt

אם האפליקציה משתמשת ב-DSL של entryProvider, אתם מספקים מטא-נתונים באמצעות הפרמטר metadata של הפונקציה entry. יש שתי פונקציות עמוסות של הפונקציה הזו: אחת שמקבלת מפה ישירות, ואחת שמקבלת פונקציית lambda שמעבירה את המפתח של הרשומה כארגומנט:

entry<Home>(metadata = mapOf("key" to "value")) { /* ... */ }
entry<Conversation>(metadata = { key: Conversation ->
    mapOf("key" to "value: ${key.id})")
}) { /* ... */ }
MetadataSnippets.kt

לספק מטא-נתונים של Scene

כברירת מחדל, Scene.metadata משתמש בפונקציית getter מותאמת אישית שמחזירה את ה-metadata של הרשומה האחרונה במאפיין entries, או מפה ריקה אם הערך הוא null. כשמטמיעים את הממשק של Scene, אפשר לשנות את פעולת ברירת המחדל הזו לפי הצורך.

שימוש ב-DSL של המטא-נתונים

שפת התחום הספציפי (DSL) של המטא-נתונים, שהושקה בגרסה 1.1.0-beta01 של הספרייה, מספקת כלי ליצירת Map<String, Any> שמשמש לאחסון מטא-נתונים, עם מניעת שגיאות הקלדה.

הגדרת מפתחות של מטא-נתונים

ה-DSL מסתמך על הממשק NavMetadataKey כדי לשמור על עקביות בסוג הערך שמשויך למפתח מטא-נתונים.

המוסכמה להגדרת מפתחות של מטא-נתונים היא לכלול אותם כאובייקטים בתצוגת עץ של המחלקה – או, במקרה של פונקציות או רכיבים, אובייקט קשור – שיקרא את הערכים שמשויכים למפתחות האלה:

// For classes such as scene strategies or nav entry decorators, you can define the keys
// as nested object.
class MySceneStrategy<T : Any> : SceneStrategy<T> {

    // ...

    object MyStringMetadataKey : NavMetadataKey<String>
}

// An example from NavDisplay.
// Because NavDisplay is a function, the metadata keys are defined in an object with the same name.
public object NavDisplay {

    public object TransitionKey :
        NavMetadataKey<AnimatedContentTransitionScope<Scene<*>>.() -> ContentTransform>
}
MetadataSnippets.kt

יצירת מטא-נתונים באמצעות DSL

כדי ליצור מפת מטא-נתונים, משתמשים בפונקציה metadata שמקבלת פרמטר למבדה. בתוך פונקציית הלמבדה, משתמשים בפונקציה put כדי להוסיף רשומות למפה באמצעות NavMetadataKey והערך המתאים.

entry<Home>(
    metadata = metadata {
        put(NavDisplay.TransitionKey) { fadeIn() togetherWith fadeOut() }
        // An additional benefit of the metadata DSL is the ability to use conditional logic
        if (condition) {
            put(MySceneStrategy.MyStringMetadataKey, "Hello, world!")
        }
    }
) {
    // ...
}
MetadataSnippets.kt

קריאת מטא-נתונים באמצעות מפתחות מטא-נתונים

ה-DSL של המטא-נתונים מספק גם פונקציות שמפשטות את קריאת המטא-נתונים באמצעות NavMetadataKey.

// import androidx.navigation3.runtime.contains
// import androidx.navigation3.runtime.get

val hasMyString: Boolean = metadata.contains(MySceneStrategy.MyStringMetadataKey)
val myString: String? = metadata[MySceneStrategy.MyStringMetadataKey]
MetadataSnippets.kt