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

در «پیمایش ۳»، از فراداده برای هم‌رسانی اطلاعات اختیاری بین عناصر مختلف کتابخانه مثل 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 کتابخانه معرفی شده است، سازنده ایمن نوعی برای ایجاد Map<String, Any> مورداستفاده برای ذخیره فراداده ارائه می‌دهد.

تعریف کلیدهای فراداده

«زبان نشانه‌گذاری داده» برای حفظ سازگاری نوع مقدار مرتبط با کلید فراداده به رابط 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

خواندن فراداده بااستفاده از کلیدهای فراداده

«زبان مدل‌سازی داده فراداده» همچنین توابعی برای ساده کردن خواندن فراداده با 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