اعمال منطق یا پوشش‌ها به مقصدها

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

یک دکوراتور سفارشی ایجاد کنید

برای ایجاد یک دکوراتور، کلاس NavEntryDecorator را ارث‌بری کرده و متدهای زیر را بازنویسی کنید:

• decorate - یک لامبدا قابل ترکیب که برای هر NavEntry در back stack شما فراخوانی می‌شود. این NavEntry به عنوان پارامتر دریافت می‌کند. این به شما امکان می‌دهد اشیاء state ایجاد کنید که به 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

اگر دکوراتور شما نیاز به دسترسی به حالت دارد، یک تابع composable ایجاد کنید که آن حالت را ایجاد کند، سپس از آن برای ساخت دکوراتور استفاده کنید. برای مثال، به کد منبع 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

چه زمانی از دکوراتور استفاده کنیم

از یک دکوراتور استفاده کنید:

• برای هر NavEntry در یک back stack یک وابستگی ایجاد کنید. برای مثال، ViewModelStoreNavEntryDecorator برای هر NavEntry یک ViewModelStore ایجاد می‌کند.
• یک شیء را به چندین NavEntry محدود کنید. برای مثال، برای به اشتراک گذاشتن یک ViewModel بین چندین ورودی.
• انجام یک عمل مشابه برای چندین NavEntry . به عنوان مثال، برای انجام عملیات ثبت وقایع، اشکال‌زدایی یا ردیابی برای هر ورودی.
• NavEntry ها را با همان تابع ترکیب‌پذیر (composable function) پوشش دهید.
• پاک‌سازی وضعیت مرتبط با NavEntry ها. برای مثال، وقتی یک ورودی از پشته حذف می‌شود، ViewModelStoreNavEntryDecorator ViewModelStore مرتبط با آن را پاک می‌کند.

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

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

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

برای مثال‌های کد بیشتر، به NavEntryDecorator مراجعه کنید.