یک چیدمان فهرست با جزئیات بسازید

با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

implementation("androidx.compose.material3.adaptive:adaptive")
implementation("androidx.compose.material3.adaptive:adaptive-layout")
implementation("androidx.compose.material3.adaptive:adaptive-navigation")

implementation 'androidx.compose.material3.adaptive:adaptive'
implementation 'androidx.compose.material3.adaptive:adaptive-layout'
implementation 'androidx.compose.material3.adaptive:adaptive-navigation'

• تطبیقی: بلوک‌های ساختمانی سطح پایین مانند HingeInfo و Posture
• تطبیق‌بندی: طرح‌بندی‌های تطبیقی ​​مانند ListDetailPaneScaffold و SupportingPaneScaffold
• adaptive-navigation: قابلیت های Composable برای پیمایش درون و بین پنجره ها و همچنین طرح بندی های تطبیقی ​​که به طور پیش فرض از ناوبری پشتیبانی می کنند مانند NavigableListDetailPaneScaffold و NavigableSupportingPaneScaffold

مطمئن شوید که پروژه شما شامل compose-material3-adaptive نسخه 1.1.0-beta1 یا بالاتر باشد.

ژست برگشتی پیش‌بینی‌کننده را انتخاب کنید

برای فعال کردن انیمیشن‌های پیش‌بینی‌کننده پیش‌بینی در Android 15 یا پایین‌تر، باید برای پشتیبانی از حرکت پیش‌بینی‌کننده برگشت شرکت کنید. برای شرکت کردن، android:enableOnBackInvokedCallback="true" را به تگ <application> یا تگ های <activity> فردی در فایل AndroidManifest.xml خود اضافه کنید. برای اطلاعات بیشتر، شرکت در حرکت پیشگویانه برگشت را ببینید.

هنگامی که برنامه شما Android 16 (سطح API 36) یا بالاتر را هدف قرار داد، پیش‌بینی بازگشت به طور پیش‌فرض فعال می‌شود.

استفاده اساسی

NavigableListDetailPaneScaffold به صورت زیر پیاده سازی کنید:

1. از کلاسی استفاده کنید که محتوای انتخاب شده را نشان دهد. از یک کلاس Parcelable برای پشتیبانی از ذخیره و بازیابی آیتم لیست انتخاب شده استفاده کنید. از افزونه kotlin-parcelize برای تولید کد برای شما استفاده کنید.
2. با rememberListDetailPaneScaffoldNavigator یک ThreePaneScaffoldNavigator ایجاد کنید.

این ناوبر برای جابجایی بین لیست، جزئیات و پنجره های اضافی استفاده می شود. با اعلام یک نوع عمومی، ناوبر وضعیت داربست (یعنی MyItem در حال نمایش) را نیز ردیابی می کند. از آنجایی که این نوع قابل تقسیم است، وضعیت می تواند توسط ناوبر ذخیره و بازیابی شود تا به طور خودکار تغییرات پیکربندی را مدیریت کند.

1. ناوبر را به NavigableListDetailPaneScaffold قابل ترکیب منتقل کنید.

2. پیاده سازی پنجره لیست خود را به NavigableListDetailPaneScaffold عرضه کنید. از AnimatedPane برای اعمال انیمیشن های صفحه پیش فرض در حین پیمایش استفاده کنید. سپس از ThreePaneScaffoldNavigator برای رفتن به قسمت جزئیات، ListDetailPaneScaffoldRole.Detail و نمایش آیتم ارسال شده استفاده کنید.

3. پیاده سازی پنجره جزئیات خود را در NavigableListDetailPaneScaffold قرار دهید.

هنگامی که پیمایش کامل شد، currentDestination شامل قسمتی است که برنامه شما به آن پیمایش کرده است، از جمله محتوای نمایش داده شده در کادر. ویژگی contentKey همان نوع مشخص شده در تماس اصلی است، بنابراین شما می توانید به هر داده ای که برای نمایش نیاز دارید دسترسی داشته باشید.

1. به صورت اختیاری، defaultBackBehavior در NavigableListDetailPaneScaffold تغییر دهید. به طور پیش‌فرض، NavigableListDetailPaneScaffold از PopUntilScaffoldValueChange برای defaultBackBehavior استفاده می‌کند.

اگر برنامه شما به الگوی پیمایش برگشتی متفاوتی نیاز دارد، می‌توانید با مشخص کردن گزینه BackNavigationBehavior دیگری، این رفتار را لغو کنید.

گزینه های BackNavigationBehavior

بخش زیر از مثال یک برنامه ایمیل با لیستی از ایمیل ها در یک بخش و نمای دقیق در قسمت دیگر استفاده می کند.

PopUntilScaffoldValueChange (پیش‌فرض و در بیشتر موارد توصیه می‌شود)

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

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

• Multi-Pane: شما در حال مشاهده یک ایمیل (مورد 1) در قسمت جزئیات هستید. با کلیک بر روی ایمیل دیگر (مورد 2) صفحه جزئیات به روز می شود، اما لیست و پنجره های جزئیات قابل مشاهده هستند. فشار دادن به عقب ممکن است از برنامه یا جریان ناوبری فعلی خارج شود.
• Single-Pane: شما آیتم 1 و سپس آیتم 2 را مشاهده می کنید، با فشار دادن به عقب مستقیماً به صفحه لیست ایمیل باز می گردید.

هنگامی که می خواهید کاربران با هر عمل برگشتی، تغییرات طرح بندی متمایز را درک کنند، از این استفاده کنید.

PopUntilContentChange

این رفتار محتوای نمایش داده شده را در اولویت قرار می دهد. اگر آیتم 1 و سپس آیتم 2 را مشاهده کنید، بدون در نظر گرفتن طرح بندی، با فشردن بازگشت به آیتم 1 باز می گردد.

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

• Multi-Pane: مورد 1 را در قسمت جزئیات مشاهده می کنید، سپس روی مورد 2 در لیست کلیک کنید. صفحه جزئیات به روز می شود. با فشار دادن به عقب، صفحه جزئیات به آیتم 1 باز می گردد.
• Single-Pane: همان بازگشت محتوا رخ می دهد.

زمانی که کاربر انتظار دارد با اکشن برگشتی به محتوایی که قبلاً مشاهده کرده است، از این استفاده کنید.

PopUntilCurrentDestinationChange

این رفتار پشته پشتی را باز می کند تا زمانی که مقصد ناوبری فعلی تغییر کند. این به طور یکسان برای طرح‌بندی‌های تک و چند صفحه‌ای صدق می‌کند.

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

صرف نظر از اینکه در یک طرح بندی تک یا چند صفحه ای هستید، با فشار دادن به عقب، فوکوس همیشه از عنصر پیمایش برجسته شده به مقصد قبلی منتقل می شود. در برنامه ایمیل ما، این بدان معنی است که نشانه بصری صفحه انتخاب شده تغییر خواهد کرد.

هنگامی که حفظ یک نشانه بصری واضح از ناوبری فعلی برای تجربه کاربر بسیار مهم است، از این استفاده کنید.

PopLatest

این گزینه فقط آخرین مقصد را از پشت پشتی حذف می کند. از این گزینه برای پیمایش به عقب بدون پرش از حالت های میانی استفاده کنید.

پس از اجرای این مراحل، کد شما باید شبیه به شکل زیر باشد:

val scaffoldNavigator = rememberListDetailPaneScaffoldNavigator<MyItem>()
val scope = rememberCoroutineScope()

NavigableListDetailPaneScaffold(
    navigator = scaffoldNavigator,
    listPane = {
        AnimatedPane {
            MyList(
                onItemClick = { item ->
                    // Navigate to the detail pane with the passed item
                    scope.launch {
                        scaffoldNavigator.navigateTo(
                            ListDetailPaneScaffoldRole.Detail,
                            item
                        )
                    }
                },
            )
        }
    },
    detailPane = {
        AnimatedPane {
            // Show the detail pane content if selected item is available
            scaffoldNavigator.currentDestination?.contentKey?.let {
                MyDetails(it)
            }
        }
    },
)
SampleListDetailPaneScaffold.kt