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

يمكنك تقديم معلومات إضافية أو تطبيق المنطق نفسه على وجهات باستخدام الفئة 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

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

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

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

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

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

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

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