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

در Navigation 3، شما از متادیتا برای اشتراک‌گذاری اطلاعات دلخواه بین اجزای مختلف کتابخانه مانند NavEntry ، Scene و NavDisplay استفاده می‌کنید. در ابتدایی‌ترین حالت، متادیتا یک Map<String, Any> است. با این حال، این کتابخانه انتزاع‌های اضافی را برای ساده‌تر کردن و ایمن‌تر کردن خواندن و نوشتن متادیتا ارائه می‌دهد .

ارائه فراداده NavEntry

اگر برنامه شما نمونه‌های NavEntry خود را مستقیماً می‌سازد، می‌توانید با استفاده از پارامتر سازنده‌ی metadata فراداده (metadata) را برای ورودی ارائه دهید:

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

اگر برنامه شما از entryProvider DSL استفاده می‌کند ، شما متادیتا را از طریق پارامتر metadata تابع entry ارائه می‌دهید. دو overload برای این تابع وجود دارد: یکی که مستقیماً یک map می‌گیرد و دیگری که یک lambda می‌گیرد که کلید entry را به عنوان آرگومان ارسال می‌کند:

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

ارائه فراداده Scene

به طور پیش‌فرض، Scene.metadata از یک getter سفارشی استفاده می‌کند که metadata آخرین ورودی در ویژگی entries آن یا یک map خالی در صورت 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>
}
MetadataSnippets.kt

ساخت فراداده با استفاده از DSL

برای ایجاد یک نقشه فراداده، از تابع metadata استفاده کنید که یک پارامتر لامبدا می‌گیرد. درون این لامبدا، از تابع 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