กำหนดค่าแอปด้วยข้อมูลเมตา

ใน Navigation 3 คุณใช้ข้อมูลเมตาเพื่อแชร์ข้อมูลที่กำหนดเองระหว่างคอมโพเนนต์ของไลบรารีต่างๆ เช่น NavEntry, Scene และ NavDisplay ข้อมูลเมตาในระดับพื้นฐานที่สุดคือMap<String, Any> อย่างไรก็ตาม ไลบรารีมีการแยกส่วนเพิ่มเติมเพื่อให้อ่าน และเขียนข้อมูลเมตาได้ง่ายขึ้นและมีความปลอดภัยด้านประเภทมากขึ้น

ระบุข้อมูลเมตา NavEntry

หากแอปสร้างอินสแตนซ์ NavEntry โดยตรง คุณจะต้องระบุข้อมูลเมตาสำหรับ รายการโดยใช้พารามิเตอร์ตัวสร้าง metadata

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

หากแอปใช้ entryProvider DSL คุณจะระบุข้อมูลเมตาผ่านพารามิเตอร์ metadata ของฟังก์ชัน entry ฟังก์ชันนี้มีโอเวอร์โหลด 2 รายการ รายการหนึ่งรับแมปโดยตรง และอีกรายการหนึ่งรับแลมบ์ดาที่ส่งคีย์ของรายการเป็นอาร์กิวเมนต์

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

ระบุข้อมูลเมตา Scene

โดยค่าเริ่มต้น Scene.metadata จะใช้ตัวรับค่าที่กำหนดเองซึ่งแสดงผล metadata ของรายการล่าสุดในพร็อพเพอร์ตี้ entries หรือแผนที่ว่าง หากเป็น null เมื่อใช้Sceneอินเทอร์เฟซ คุณจะลบล้างลักษณะการทำงานเริ่มต้นนี้ได้ตามต้องการ

ใช้ DSL ข้อมูลเมตา

เปิดตัวใน1.1.0-beta01ของไลบรารี ข้อมูลเมตาภาษาเฉพาะโดเมน (DSL) มีตัวสร้างที่ปลอดภัยต่อประเภทสำหรับการสร้างMap<String, Any>ที่ใช้จัดเก็บข้อมูลเมตา

กำหนดคีย์ข้อมูลเมตา

DSL ใช้ประโยชน์จากอินเทอร์เฟซ NavMetadataKey เพื่อให้ประเภทของ ค่าที่เชื่อมโยงกับคีย์ข้อมูลเมตาสอดคล้องกัน

ธรรมเนียมในการกำหนดคีย์ข้อมูลเมตาคือการรวมคีย์เหล่านั้นเป็นออบเจ็กต์ที่ซ้อนกัน ของคลาส หรือในกรณีของฟังก์ชันหรือ Composable ให้ใช้ออบเจ็กต์ที่เกี่ยวข้อง ซึ่ง จะอ่านค่าที่เชื่อมโยงกับคีย์เหล่านั้น

// 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 ภายใน 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