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

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

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

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

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

אם האפליקציה שלכם משתמשת ב-entryProviderDSL, אתם מספקים מטא-נתונים באמצעות הפרמטר 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 של מטא-נתונים

בגרסה 1.1.0-beta01 של הספרייה הושקה שפה ספציפית לתחום (DSL) של מטא-נתונים, שמספקת כלי ליצירת 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, שמקבלת פרמטר למדה. בתוך פונקציית ה-LAMBDA הזו, משתמשים בפונקציה 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