使用中繼資料設定應用程式

在 Navigation 3 中，您可以使用中繼資料在不同的程式庫元件之間共用任意資訊，例如 NavEntry、Scene 和 NavDisplay。中繼資料基本上是Map<String, Any>。不過，程式庫提供額外的抽象層，可簡化中繼資料的讀取和寫入作業，並提高類型安全性。

提供 NavEntry 中繼資料

如果應用程式直接建構 NavEntry 執行個體，請使用 metadata 建構函式參數提供項目的中繼資料：

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

如果應用程式使用 entryProvider DSL，請透過 entry 函式的 metadata 參數提供中繼資料。這個函式有兩種超載：一種是直接採用對應，另一種是採用 lambda，將項目的鍵做為引數傳遞：

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

提供 Scene 中繼資料

根據預設，Scene.metadata 會使用自訂 getter，傳回其 entries 屬性中最後一個項目的 metadata，如果為 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>
}

使用 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!")
        }
    }
) {
    // ...
}

使用中繼資料鍵讀取中繼資料

中繼資料 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]