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

List-detail یک الگوی رابط کاربری است که از یک طرح بندی دو صفحه ای تشکیل شده است که در آن یک صفحه فهرستی از آیتم ها را ارائه می دهد و صفحه دیگری جزئیات موارد انتخاب شده از لیست را نمایش می دهد.

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

الگوی رابط کاربری را با ListDetailPaneScaffold پیاده سازی کنید

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

وابستگی ها را اعلام کنید

ListDetailPaneScaffold بخشی از کتابخانه طرح تطبیقی ​​Material 3 است.

برنامه شما باید دارای وابستگی هایی برای سه کتابخانه Material 3 مرتبط باشد:

• تطبیقی ​​- بلوک‌های ساختمانی سطح پایین مانند HingeInfo و Posture
• طرح‌بندی تطبیقی ​​– طرح‌بندی‌های تطبیقی ​​مانند ListDetailPaneScaffold و SupportingPaneScaffold
  • ناوبری تطبیقی ​​- قابل ترکیب برای پیمایش درون و بین پنجره ها

وابستگی ها را به فایل build.gradle برنامه یا ماژول خود اضافه کنید:

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

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

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

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

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

   @Parcelize
   class MyItem(val id: Int) : Parcelable
   SampleListDetailPaneScaffold.kt

2. یک ThreePaneScaffoldNavigator با rememberListDetailPaneScaffoldNavigator ایجاد کنید و یک BackHandler اضافه کنید. این ناوبر برای جابجایی بین لیست، جزئیات و پنجره های اضافی استفاده می شود. با اعلام یک نوع عمومی، ناوبر وضعیت داربست (یعنی MyItem در حال نمایش) را نیز ردیابی می کند. از آنجایی که این نوع قابل تقسیم است، وضعیت می تواند توسط ناوبر ذخیره و بازیابی شود تا به طور خودکار تغییرات پیکربندی را مدیریت کند. BackHandler برای پیمایش به عقب با استفاده از ژست یا دکمه بازگشت سیستم پشتیبانی می کند. رفتار مورد انتظار دکمه برگشت برای ListDetailPaneScaffold به اندازه پنجره و مقدار داربست فعلی بستگی دارد. اگر ListDetailPaneScaffold می تواند از بازگشت به حالت فعلی پشتیبانی کند، پس canNavigateBack() true است و BackHandler فعال می کند.

   val navigator = rememberListDetailPaneScaffoldNavigator<MyItem>()
   
   BackHandler(navigator.canNavigateBack()) {
       navigator.navigateBack()
   }
   SampleListDetailPaneScaffold.kt

3. scaffoldState از navigator به ListDetailPaneScaffold قابل ترکیب منتقل کنید.

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       // ...
   )
   SampleListDetailPaneScaffold.kt

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

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       listPane = {
           AnimatedPane {
               MyList(
                   onItemClick = { item ->
                       // Navigate to the detail pane with the passed item
                       navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, item)
                   }
               )
           }
       },
       // ...
   )
   SampleListDetailPaneScaffold.kt

5. پیاده سازی پنجره جزئیات خود را در ListDetailPaneScaffold قرار دهید. هنگامی که پیمایش کامل شد، currentDestination شامل صفحه‌ای است که برنامه شما به آن پیمایش کرده است، از جمله محتوای نمایش داده شده در صفحه. ویژگی content همان نوع مشخص شده در فراخوانی اصلی به خاطر سپردن ( MyItem در این مثال) است، بنابراین شما همچنین می توانید برای هر داده ای که نیاز به نمایش دارید به ویژگی دسترسی داشته باشید.

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       listPane =
       // ...
       detailPane = {
           AnimatedPane {
               navigator.currentDestination?.content?.let {
                   MyDetails(it)
               }
           }
       },
   )
   SampleListDetailPaneScaffold.kt

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

val navigator = rememberListDetailPaneScaffoldNavigator<MyItem>()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}

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