شارك المقالة
شرح ExpansionPanelList.radio في Flutter لقائمة قابلة للطي

شرح ExpansionPanelList.radio في Flutter لقائمة قابلة للطي

بناء ExpansionPanelList.radio في Flutter لفتح لوحة واحدة، مع معرّفات مستقرة وفهم callback والفرق عن القائمة متعددة الفتح ودون حزمة خارجية.

بناء ExpansionPanelList.radio في Flutter لفتح لوحة واحدة، مع معرّفات مستقرة وفهم callback والفرق عن القائمة متعددة الفتح ودون حزمة خارجية.

اختر سياسة الفتح أولًا

قائمة قابلة للطي مناسبة لأسئلة أو تفاصيل مرتبطة بعناوين قصيرة. حدد هل يُسمح بفتح عدة عناصر أم عنصر واحد فقط. ExpansionPanelList العادي يحتاج منك إدارة isExpanded لكل لوحة، بينما radio يدير الاختيار الواحد داخليًا. لا تخلط ذلك بقائمة Drawer أو Dropdown لاختيار قيمة؛ تشابه حركة الظهور لا يجعل المكوّنات تؤدي المهمة نفسها. المثال يشرح ثلاث فقرات تعليمية، ولا يحتاج حزمة expandable أو أصناف EmptyModel غير متاحة في ملف آخر.

هوية مستقرة لكل لوحة

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

من يملك حالة التوسيع؟

في صيغة radio يدير المكوّن فتح عنصر وإغلاق السابق، ولذلك لا تحتاج قلب bool في كل صف كما تفعل مع الصيغة العادية. expansionCallback يمكن استخدامه لملاحظة التغيير، وقد يأتي لأكثر من لوحة عند فتح أخرى وإغلاق السابقة؛ لا تعتبر كل استدعاء نقرة مستقلة أو إذنًا لإرسال طلب مكلف. initialOpenPanelValue يحدد البداية، وليس واجهة تحكم مستمر تعيد فرض القيمة في كل build. إذا احتجت إدارة خارجية دقيقة فاختر بنية توافق متطلباتك بدل الاعتماد على خاصية ابتدائية كأنها controller.

المحتوى والتمرير

headerBuilder يبني العنوان والوسيط الثاني فيه يعبر عن حالة التوسيع، وليس فهرس العنصر الذي تسميه عشوائيًا index ثم تعتمد عليه للوصول إلى قائمة. body يحتوي التفاصيل، ويمكن إضافة padding منطقي دون ارتفاع ثابت يقص النص. ضع القائمة داخل تمرير مناسب عندما تكون العناصر قليلة كما هنا. عند آلاف العناصر أو محتوى ثقيل راجع البناء والتحميل واختيار مكوّن يناسب الحجم؛ ExpansionPanelList ليس تلقائيًا قائمة lazy لكل نوع من البيانات لمجرد أنه يعرض عدة صفوف.

قابلية القراءة والبيانات الحساسة

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

المراجعة قبل النقل للمشروع

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

مثال مستقل للتجربة

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

import 'package:flutter/material.dart';
void main() => runApp(const MaterialApp(home: DemoPage()));
class LessonSection {
  const LessonSection(this.id, this.title, this.body);
  final String id;
  final String title;
  final String body;
}
class DemoPage extends StatelessWidget {
  const DemoPage({super.key});
  static const _sections = [
    LessonSection('setup', 'Project setup', 'Create a small test project before changing the production app.'),
    LessonSection('layout', 'Layout constraints', 'Choose a bounded parent and test long text at larger text scales.'),
    LessonSection('review', 'Review behavior', 'Open another panel and check that the previous panel closes.'),
  ];
  @override
  Widget build(BuildContext context) => Scaffold(
    appBar: AppBar(title: const Text('One expanded panel')),
    body: SingleChildScrollView(padding: const EdgeInsets.all(16), child: ExpansionPanelList.radio(
      children: [
        for (final section in _sections)
          ExpansionPanelRadio(
            value: section.id,
            canTapOnHeader: true,
            headerBuilder: (_, isExpanded) => ListTile(title: Text(section.title)),
            body: Padding(padding: const EdgeInsets.all(16), child: Align(
              alignment: AlignmentDirectional.centerStart, child: Text(section.body),
            )),
          ),
      ],
    )),
  );
}

مرجع الواجهة البرمجية

راجع التوثيق الرسمي لمطابقة السلوك مع إصدار Flutter المستخدم. نجاح المثال في مساحة واحدة لا يثبت توافق التصميم مع جميع الشاشات؛ اختبر حدود الانتقال والاتجاه واللغة والنص الطويل.

الصور والفيديو من الشرح السابق

الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.

How to use Expansion Panel List in Flutter
شاهد أيضًا
مقالات ذات صلة
🚫 مانع الإعلانات مفعل

يجب إيقاف مانع الإعلانات لاستكمال تصفح الموقع