إعداد تطبيقك باستخدام البيانات الوصفية

في 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. هناك حمولتان زائدتان لهذه الدالة: إحداهما تأخذ خريطة مباشرةً والأخرى تأخذ تعبير lambda يمرّر مفتاح الإدخال كوسيطة:

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 الخاصة بالبيانات الوصفية

تم تقديم لغة خاصة بالمجال (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 التي تأخذ مَعلمة 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