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

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