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

في Navigation 3، يمكنك استخدام البيانات الوصفية لمشاركة معلومات عشوائية بين مكوّنات المكتبة المختلفة، مثل NavEntry وScene وNavDisplay. بشكل أساسي، البيانات الوصفية هي Map<String, Any>. ومع ذلك، توفّر المكتبة تجريدات إضافية لتسهيل قراءة البيانات الوصفية وكتابتها وجعلها أكثر أمانًا من حيث النوع.

تقديم البيانات الوصفية لـ NavEntry

إذا كان تطبيقك ينشئ مثيلات NavEntry مباشرةً، يمكنك تقديم بيانات وصفية للإدخال باستخدام مَعلمة الدالة الإنشائية metadata:

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

إذا كان تطبيقك يستخدم لغة DSL في entryProvider، يمكنك تقديم البيانات الوصفية من خلال المَعلمة 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 تلقائيًا دالة getter مخصّصة تعرض metadata لآخر إدخال في السمة entries، أو خريطة فارغة إذا كانت القيمة null. عند تنفيذ واجهة Scene، يمكنك إلغاء هذا الإعداد التلقائي حسب الحاجة.

استخدام لغة DSL للبيانات الوصفية

تم تقديم لغة domain-specific language (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