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

يمكنك تقديم معلومات إضافية أو تطبيق المنطق نفسه على الوجهات باستخدام فئة 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. تكون هذه الدالة مفيدة عندما يكون لديك عدة أنشطة سابقة، ولكل منها مجموعة من أدوات التزيين (يُرجى الاطّلاع على وصفة الرمز هذه لمزيد من التفاصيل). تُرجع الدالة قائمة مزخرفة من NavEntrys التي يمكنك استخدامها مع 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

بدءًا من الإصدار 1.2.0 من Navigation 3، يمكنك استخدام 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 بين إدخالات متعددة.
• يمكنك تنفيذ الإجراء نفسه على عدة NavEntry. على سبيل المثال، لإجراء عمليات التسجيل أو تصحيح الأخطاء أو التتبُّع لكل إدخال.
• يمكنك تضمين NavEntry في الدالة المركّبة نفسها.
• تنظيف الحالة المرتبطة بـ NavEntrys على سبيل المثال، عند إزالة إدخال من الأنشطة السابقة، يمحو ViewModelStoreNavEntryDecorator الـ ViewModelStore المرتبط به.

لا تستخدِم عنصر تزيين من أجل:

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

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

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