Định cấu hình ứng dụng bằng siêu dữ liệu

Trong Navigation 3, bạn sử dụng siêu dữ liệu để chia sẻ thông tin tuỳ ý giữa các thành phần thư viện khác nhau, chẳng hạn như NavEntry, Scene và NavDisplay. Về cơ bản, siêu dữ liệu là một Map<String, Any>. Tuy nhiên, thư viện này cung cấp các lớp trừu tượng bổ sung để giúp việc đọc và ghi siêu dữ liệu trở nên đơn giản và an toàn hơn về loại.

Cung cấp siêu dữ liệu `NavEntry`

Nếu ứng dụng của bạn tạo trực tiếp các thực thể NavEntry, bạn sẽ cung cấp siêu dữ liệu cho mục nhập bằng cách sử dụng tham số hàm khởi tạo metadata:

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

Nếu ứng dụng của bạn sử dụng DSL entryProvider, bạn sẽ cung cấp siêu dữ liệu thông qua tham số metadata của hàm entry. Có 2 phương thức nạp chồng của hàm này: một phương thức trực tiếp lấy bản đồ và một phương thức lấy lambda truyền khoá của mục nhập làm đối số:

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

Cung cấp siêu dữ liệu `Scene`

Theo mặc định, Scene.metadata sử dụng một phương thức getter tuỳ chỉnh trả về metadata của mục nhập cuối cùng trong thuộc tính entries hoặc một bản đồ trống nếu đó là null. Khi triển khai giao diện Scene, bạn có thể ghi đè hành vi mặc định này nếu cần.

Sử dụng DSL siêu dữ liệu

Được giới thiệu trong bản phát hành 1.1.0-beta01 của thư viện, ngôn ngữ dành riêng cho miền (DSL) siêu dữ liệu cung cấp một trình tạo an toàn về kiểu để tạo Map<String, Any> dùng để lưu trữ siêu dữ liệu.

Xác định khoá siêu dữ liệu

DSL dựa vào giao diện NavMetadataKey để duy trì tính nhất quán của loại giá trị được liên kết với một khoá siêu dữ liệu.

Quy ước xác định khoá siêu dữ liệu là đưa các khoá đó vào dưới dạng các đối tượng lồng nhau của lớp (hoặc trong trường hợp các hàm hoặc thành phần kết hợp, một đối tượng có liên quan) sẽ đọc các giá trị được liên kết với các khoá đó:

// 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

Tạo siêu dữ liệu bằng DSL

Để tạo một bản đồ siêu dữ liệu, hãy sử dụng hàm metadata. Hàm này nhận một tham số lambda. Trong hàm lambda này, hãy dùng hàm put để thêm các mục vào tập hợp map bằng cách dùng NavMetadataKey và giá trị tương ứng.

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

Đọc siêu dữ liệu bằng khoá siêu dữ liệu

DSL siêu dữ liệu cũng cung cấp các hàm để đơn giản hoá việc đọc siêu dữ liệu bằng 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