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

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

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

تنفيذ نمط واجهة المستخدم باستخدام 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