اعمال منطق یا بسته‌بندی به مقصدها

بااستفاده از کلاس NavEntryDecorator می‌توانید اطلاعات اضافی ارائه دهید یا منطق یکسانی را برای مقصدها اعمال کنید. این کلاس هر NavEntry را در پشته پشتی با یک تابع ترکیب‌شدنی می‌پیچد. به‌عبارتی دیگر، محتوای ورودی را تزیین می‌کند.

ایجاد تزئین‌کننده سفارشی

برای ایجاد یک تزئین‌کننده، کلاس NavEntryDecorator را گسترش دهید و روش‌های زیر را ملغی کنید:

• ‫decorate - لامبدای ترکیبی که برای هر 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 استفاده کنید.
• تزئین‌کننده را مستقیماً بااستفاده از پارامتر entryDecorators به NavDisplay ارائه دهید. ‫NavDisplay تماس rememberDecoratedNavEntries در پشت صحنه و ورودی‌های تزئین‌شده را نمایش می‌دهد.

افزودن تزئین‌کننده پیش‌فرض

«پیمایش ۳» شامل تزئین‌کننده‌ای پیش‌فرض به‌نام SaveableStateHolderNavEntryDecorator است که امکان می‌دهد وضعیت NavEntry در تغییرات پیکربندی و پایان فرایند حفظ شود. محتوای NavEntry را با SaveableStateProvider می‌پیچد که باعث می‌شود تماس‌های rememberSaveable درون محتوای NavEntry به‌درستی کار کنند.

مگر اینکه دکوراتور شما SaveableStateProvider را ارائه دهد، باید SaveableStateHolderNavEntryDecorator را به‌عنوان اولین دکوراتور در فهرست دکوراتورهای ارائه‌شده خود اضافه کنید. بااستفاده از rememberSaveableStateHolderNavEntryDecorator ایجاد شده است.

برای مثال:

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

گذراندن نتایج بااستفاده از ResultEventBusNavEntryDecorator

از «پیمایش ۳» ۱.۲.۰، می‌توانید از ResultEventBusNavEntryDecorator برای ارائه ResultEventBus به هر NavEntry بااستفاده از ترکیب محلی LocalResultEventBus استفاده کنید.

به‌طور پیش‌فرض، rememberResultEventBusNavEntryDecorator نمونه ResultEventBus خود را به‌صورت داخلی بااستفاده از rememberResultEventBus ایجاد و به‌خاطر می‌سپارد. اگر نیاز دارید خارج از سلسله‌مراتب تزئین‌کننده (مثلاً در داربست برنامه سطح بالا) به گذرگاه رویداد دسترسی پیدا کنید، می‌توانید با فراخوانی rememberResultEventBus و انتقال آن به rememberResultEventBusNavEntryDecorator(resultEventBus)، ResultEventBus را بالا ببرید:

val resultEventBus = rememberResultEventBus()

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

برای جزئیات بیشتر درباره ارسال و مشاهده نتایج، به برگرداندن نتایج مراجعه کنید.

چه زمانی از تزئین‌کننده استفاده کنیم

از تزئین‌کننده برای موارد زیر استفاده کنید:

• برای هر NavEntry در پشته برگشت، وابستگی ایجاد کنید. برای مثال، ViewModelStoreNavEntryDecorator برای هر NavEntry یک ViewModelStore ایجاد می‌کند.
• نتایج را منتقل کنید و بین مقصدها ارتباط برقرار کنید. برای مثال، ResultEventBusNavEntryDecorator ResultEventBus را برای مقصدها در پشته برگشت ارائه می‌دهد.
• دامنه شیء را به چند NavEntry محدود کنید. برای مثال، برای هم‌رسانی ViewModel بین چند ورودی.
• همین کنش را برای چند NavEntry انجام دهید. برای مثال، برای انجام عملیات گزارش‌گیری، اشکال‌زدایی، یا ردیابی برای هر ورودی.
• ‫NavEntry را با همان تابع ترکیب‌پذیر دربر بگیرید.
• وضعیت منسوب به NavEntry ثانیه پاک‌سازی می‌شود. برای مثال، وقتی ورودی از پشته پشتی برداشته می‌شود، ViewModelStoreNavEntryDecorator ViewModelStore منسوب به آن را پاک می‌کند.

از تزئین‌کننده برای موارد زیر استفاده نکنید:

• وابستگی را به یک NavEntry منتقل کنید.
• وابستگی‌هایی را ارائه دهید که محدوده آن‌ها گسترده‌تر از پشته برگشت باشد.

در هر دو این موارد، وابستگی را مستقیماً هنگام ایجاد NavEntry به‌جای آن منتقل کنید.

برای نمونه‌های کد بیشتر، NavEntryDecorator را ببینید.