تطبيق منطق أو أغلفة على الوجهات

يمكنك تقديم معلومات إضافية أو تطبيق المنطق نفسه على وجهات باستخدام الفئة NavEntryDecorator. يغلّف هذا الصف كل NavEntry في حزمة الأنشطة السابقة باستخدام دالة مركّبة. بعبارة أخرى، تزيّن هذه السمة محتوى الإدخال.

إنشاء أداة تزيين مخصّصة

لإنشاء أداة تزيين، عليك توسيع فئة NavEntryDecorator وتجاوز الطرق التالية:

• ‫decorate: دالة lambda قابلة للإنشاء يتم استدعاؤها لكل NavEntry في حزمة الخلف. تتلقّى NavEntry كمعلَمة. يتيح لك ذلك إنشاء عناصر حالة يتم ربطها بمفتاح contentKey الخاص بالإدخال. يمكنك استخدام CompositionLocalProvider لتوفير التبعيات لمحتوى الإدخال. يمكنك أيضًا تضمين المحتوى في دالة مركّبة أو تشغيل تأثيرات جانبية. يجب دائمًا استدعاء entry.Content() داخل هذا الإجراء.
• ‫onPop: دالة ردّ نداء يتم استدعاؤها عند إزالة NavEntry من الأنشطة السابقة ومغادرته التكوين. يتلقّى هذا الحقل contentKey الخاص بالإدخال الذي تمت إزالته. استخدِم contentKey لتحديد أي حالة مرتبطة بهذا الإدخال وإزالتها.

يوضّح المثال التالي كيفية توسيع الفئة NavEntryDecorator لإنشاء أداة تزيين مخصّصة.

// import androidx.navigation3.runtime.NavEntryDecorator
class CustomNavEntryDecorator<T : Any> : NavEntryDecorator<T>(
    decorate = { entry ->
        Log.d("CustomNavEntryDecorator", "entry with ${entry.contentKey} entered composition and was decorated")
        entry.Content()
    },
    onPop = { contentKey -> Log.d("CustomNavEntryDecorator", "entry with $contentKey was popped") }
)
DecoratorSnippets.kt

إذا كان العنصر الزخرفي يحتاج إلى الوصول إلى الحالة، أنشئ دالة مركّبة تنشئ هذه الحالة ثم استخدِمها لإنشاء العنصر الزخرفي. للاطّلاع على مثال للتنفيذ، راجِع الرمز المصدر الخاص rememberSaveableStateHolderNavEntryDecorator. يؤدي ذلك إلى إنشاء الحالة - وهي SaveableStateHolder - واستخدامها لإنشاء أداة الزخرفة.

تزيين الأنشطة السابقة

بعد إنشاء NavEntryDecorator، يمكنك تزيين الإدخالات في سجلّ الرجوع بإحدى الطريقتَين التاليتَين:

• استخدِم rememberDecoratedNavEntries. تكون هذه الدالة مفيدة عندما يكون لديك عدة حِزم سابقة، كل منها يتضمّن مجموعة خاصة من أدوات التزيين (راجِع وصفة التعليمات البرمجية هذه لمزيد من التفاصيل). تُرجع الدالة قائمة مزيّنة من NavEntry يمكنك استخدامها مع NavDisplay.
• قدِّم أداة التزيين مباشرةً إلى NavDisplay باستخدام المَعلمة entryDecorators. تُجري NavDisplay عمليات rememberDecoratedNavEntries في الخلفية وتعرض الإدخالات المعدَّلة.

تضمين أداة التزيين التلقائية

يتضمّن Navigation 3 أداة تزيين تلقائية باسم SaveableStateHolderNavEntryDecorator تتيح الاحتفاظ بحالة NavEntry عند حدوث تغييرات في الإعدادات أو إيقاف العملية نهائيًا. يتم تضمين محتوى NavEntry في SaveableStateProvider، ما يتيح عمل طلبات rememberSaveable داخل محتوى NavEntry بشكل صحيح.

ما لم يوفّر الديكور SaveableStateProvider، عليك تضمين SaveableStateHolderNavEntryDecorator كأول ديكور في قائمة الديكورات التي تقدّمها. يتم إنشاؤه باستخدام rememberSaveableStateHolderNavEntryDecorator.

على سبيل المثال:

// import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
NavDisplay(
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        remember { CustomNavEntryDecorator() }
    ),
    // ...
)
DecoratorSnippets.kt

تمرير النتائج باستخدام ResultEventBusNavEntryDecorator

بدءًا من الإصدار 3 1.2.0 من Navigation، يمكنك استخدام ResultEventBusNavEntryDecorator لتوفير ResultEventBus لكل NavEntry باستخدام LocalResultEventBus composition local.

تنشئ rememberResultEventBusNavEntryDecorator تلقائيًا نسخة ResultEventBus خاصة بها وتتذكّرها داخليًا باستخدام rememberResultEventBus. إذا كنت بحاجة إلى الوصول إلى ناقل الأحداث خارج التسلسل الهرمي لأداة التزيين (مثلًا في بنية التطبيق ذات المستوى الأعلى)، يمكنك نقل ResultEventBus من خلال استدعاء rememberResultEventBus وتمريره إلى rememberResultEventBusNavEntryDecorator(resultEventBus):

val resultEventBus = rememberResultEventBus()

NavDisplay(
    /* ... */
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        rememberResultEventBusNavEntryDecorator(resultEventBus = resultEventBus)
    )
)
DecoratorSnippets.kt

لمزيد من التفاصيل حول إرسال النتائج ومراقبتها، يُرجى الاطّلاع على عرض النتائج.

حالات استخدام أداة التزيين

يمكنك استخدام أداة تزيين لإجراء ما يلي:

• أنشئ عنصرًا تابعًا لكل NavEntry في حزمة سابقة. على سبيل المثال، ينشئ ViewModelStoreNavEntryDecorator ViewModelStore لكل NavEntry.
• تمرير النتائج والتواصل بين الوجهات على سبيل المثال، يوفّر ResultEventBusNavEntryDecorator ResultEventBus للوجهات في حزمة الخلفية.
• تحديد نطاق عنصر لعدة NavEntry. على سبيل المثال، لمشاركة ViewModel بين عدة إدخالات.
• تنفيذ الإجراء نفسه لعدة NavEntrys على سبيل المثال، لتنفيذ عمليات التسجيل أو تصحيح الأخطاء أو التتبُّع لكل إدخال.
• لفّ NavEntrys باستخدام الدالة المركّبة نفسها.
• محو الحالة المرتبطة بـ NavEntry على سبيل المثال، عند إزالة إدخال من الأنشطة السابقة، يمحو ViewModelStoreNavEntryDecorator ViewModelStore المرتبط به.

لا تستخدِم أداة تزيين في الحالات التالية:

• تمرير عنصر تابع إلى NavEntry واحد
• قدِّم عناصر التبعية التي يكون نطاقها أوسع من حزمة الخلف.

في كلتا الحالتين، مرِّر العنصر التابع مباشرةً عند إنشاء NavEntry بدلاً من ذلك.

للاطّلاع على المزيد من أمثلة الرموز، راجِع NavEntryDecorator.