پیکربندی برنامه با فراداده

در 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 ارائه می‌دهید. دو سربارگذاری برای این تابع وجود دارد: یکی که مستقیماً نقشه را می‌گیرد و دیگری که لامبدا را می‌گیرد و کلید ورودی را به‌عنوان آرگومان ارسال می‌کند:

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 متکی است تا نوع مقدار مرتبط با کلید فراداده را ثابت نگه دارد.

قرارداد تعریف کلیدهای فراداده این است که آن‌ها را به‌عنوان اشیاء تودرتو از کلاس (یا درمورد توابع یا ترکیب‌پذیرها، یک شیء مرتبط) اضافه کنید که مقادیر مرتبط با آن کلیدها را می‌خواند:

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