إنشاء تخطيط على تفاصيل القائمة

تفاصيل القائمة هو نمط واجهة مستخدِم يتألّف من تنسيق مزدوج اللوحة يعرِض فيه أحدهما قائمة بالعناصر ويعرِض الآخر تفاصيل العناصر التي تم اختيارها من القائمة.

يُعد النمط مفيدًا بشكل خاص للتطبيقات التي توفر معلومات معلومات حول عناصر المجموعات الكبيرة، مثل برنامج بريد إلكتروني الذي يحتوي على قائمة بالرسائل الإلكترونية والمحتوى التفصيلي لكل رسالة بريد إلكتروني. يمكن أيضًا استخدام تنسيق "القائمة التفصيلية" للمسارات الأقل أهمية، مثل تقسيم الإعدادات المفضّلة للتطبيق إلى قائمة بفئات تتضمّن الإعدادات المفضّلة لكل فئة في لوحة التفاصيل.

تنفيذ نمط واجهة المستخدم باستخدام ListDetailPaneScaffold

ListDetailPaneScaffold هي أداة قابلة للإنشاء تبسِّط تنفيذ نمط قائمة تفاصيل في تطبيقك. يمكن أن يتكون سقالة تفاصيل القائمة مما يصل إلى ثلاثة أجزاء: جزء القائمة وجزء التفاصيل وجزء إضافي اختياري. تعالج العناصر الأساسية عمليات حساب مساحة الشاشة. عندما يكون حجم الشاشة كافيًا يتم عرض جزء التفاصيل إلى جانب جزء القائمة. في أحجام الشاشة الصغيرة، ينتقل الهيكل العظمي تلقائيًا إلى عرض القائمة أو لوحة التفاصيل في وضع ملء الشاشة.

الشكل 1. عندما يكون حجم الشاشة كافيًا، يتم عرض لوحة التفاصيل بجانب لوحة القائمة.

الشكل 2. عندما تكون مساحة الشاشة محدودة، تشغل لوحة التفاصيل (بعد اختيار عنصر) المساحة الكاملة.

تعريف التبعيات

ListDetailPaneScaffold هو جزء من مكتبة التنسيق التكيُّفي Material 3 .

أضِف التبعيات الثلاثة التالية ذات الصلة إلى ملف build.gradle في التطبيق أو الوحدة:

Kotlin

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
• ‫adaptive-layout: التنسيقات التكيُّفية، مثل ListDetailPaneScaffold و SupportingPaneScaffold
• ‫adaptive-navigation: عناصر قابلة للتجميع للتنقّل داخل اللوحة وبين اللوحات

الاستخدام الأساسي

تنفيذ 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