Đị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. Ở mức cơ bản nhất, siêu dữ liệu là một Map<String, Any>. Tuy nhiên, thư viện này cung cấp thêm các lớp trừu tượng để 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ề kiểu.

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

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

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

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ó hai phương thức nạp chồng của hàm này: một phương thức lấy trực tiếp 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})")
}) { /* ... */ }

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

Theo mặc định, Scene.metadata sử dụng 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 thuộc tính đó 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 để giữ cho loại giá trị liên kết với khoá siêu dữ liệu nhất quán.

Quy ước để xác định khoá siêu dữ liệu là đưa các khoá đó vào dưới dạng đối tượng lồng nhau của lớp (hoặc trong trường hợp 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ị 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>
}

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

Để tạo 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 sử dụng hàm put để thêm các mục vào bản đồ bằng cách sử 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!")
        }
    }
) {
    // ...
}

Đọ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]