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

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

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

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