انتقل إلى المحتوى

القائمة

احصل على Ritla UI

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

فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:

افتح في Figma

المعاينة

«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.

المعاينةالكود
إنجليزيمعكوسعربي
← RTL

التثبيت

  1. أضف المكوّن

    npx ritla add list

    ويعمل أيضًا مع shadcn: npx shadcn@latest add @ritla/list

  2. الاعتماديات التي يضيفها

    @phosphor-icons/react

  3. أو انسخه يدويًا

    التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.

الاستخدام

list.tsx
import { List, ListItem } from "@/components/ui/list";<List aria-label="Team">  <ListItem leading={<Avatar name="Omar Haddad" size="sm" decorative />} supportingText="Product designer">    Omar Haddad  </ListItem></List>

أمثلة

أيقونة وسطر علوي

‏leadingIcon يضع الأيقونة في دائرة 40 بكسل. الصفوف هنا أزرار (onClick)، فتظهر خلفية المرور عليها.

إنجليزيمعكوسعربي
← RTL

صف قابل للسحب

اسحب نحو النهاية للأرشفة، ونحو البداية للتأجيل أو الحذف. البداية والنهاية تتبعان اتجاه القراءة. وزر ⋮ يعرض الإجراءات نفسها للوحة المفاتيح وقارئ الشاشة والفأرة.

إنجليزيمعكوسعربي
← RTL

صف معطّل

‏disabled يلوّن النص بلون التعطيل ويخفف العنصرين في البداية والنهاية إلى 48%، ويزيل التمرير. صف الزر يصبح زرًا معطّلًا، وصف الرابط يفقد وجهته. قل السبب في النص المساند.

إنجليزيمعكوسعربي
← RTL

مرجع الخصائص

List

الخاصيةالنوعالافتراضيالوصف
aria-labelstringلا يوجداسم القائمة إن كان في الصفحة أكثر من قائمة.
childrenReactNodeلا يوجدعناصر ListItem أو SwipeableListItem.

ListItem

الخاصيةالنوعالافتراضيالوصف
childrenReactNodeلا يوجدخاصية Headline.
overlineReactNodeلا يوجدخاصية Overline: سطر قصير فوق العنوان.
supportingTextReactNodeلا يوجدخاصية Supporting text تحت العنوان.
leadingReactNodeلا يوجدعنصر البداية: صورة رمزية أو علم أو صورة.
leadingIconIconComponentلا يوجدأيقونة في دائرة 40 بكسل (النوع Icon).
trailingReactNodeلا يوجدخاصية Show Tags: وسم أو أي عنصر في النهاية.
hrefstringلا يوجديجعل الصف رابطًا.
renderReactElementلا يوجدرابط التوجيه (<Link>) بمظهر الصف.
onClickMouseEventHandlerلا يوجديجعل الصف زرًا.
disabledbooleanfalseخاصية State = Disabled. في السحب: لا سحب، وزر ⋮ معطّل.

SwipeableListItem

الخاصيةالنوعالافتراضيالوصف
leadingActionsSwipeAction[]لا يوجدإجراءات تظهر في البداية عند السحب نحو النهاية (Swipe = Leading).
trailingActionsSwipeAction[]لا يوجدإجراءات تظهر في النهاية عند السحب نحو البداية (Swipe = Trailing).
SwipeAction{ label, icon, tone?: "brand" | "warning" | "danger", onAction }لا يوجدإجراء واحد بعرض 88 بكسل.
menubooleantrueزر ⋮ بالإجراءات نفسها، كي لا يكون السحب الطريق الوحيد.
menuLabelstring"More actions"اسم زر ⋮، بلغة الصفحة افتراضيًا.
…ListItem propsلا يوجدكل خصائص ListItem.

إرشادات الاستخدام

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

1. قائمة أم جدول أم بطاقات

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

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

2. أجزاء عنصر القائمة

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

العنوان أولًا، والتفاصيل ثانيًا

قائمة نشاط المدفوعات.

افعل: عنوان قصير، والتفاصيل تحتهيمسح الناس الأسماء، ثم يقرؤون المبلغ والوقت.
تجنّب: كل شيء في العنوانتلتف العناوين إلى ثلاثة أسطر، ويكررها النص المساعد.

افعل

  • السطر العلوي للوقت أو الفئة: «اليوم، 09:41».
  • اجعل العنوان الشيء الوحيد الذي يبحث عنه الناس.
  • النص المساعد للتفاصيل، في سطر أو سطرين.
  • الوسم اللاحق لعدد أو حالة.
  • نوع بادئ واحد لكل قائمة، أو الفراغ لإبقاء النص محاذيًا.

تجنّب

  • تكرار العنوان في النص المساعد.
  • جملة في العنوان؛ تلتف وتدفع القائمة إلى الأسفل.
  • ترك صفوف بلا عنصر بادئ بجوار صفوف لها عنصر.
  • وسم على كل صف؛ يفقد معناه.

3. كتابة نص القائمة

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

افعل

  • ابدأ بالاسم أو العنوان أو الحدث.
  • العنوان سطر واحد، والنص المساعد سطران.
  • صيغة وقت واحدة في القائمة: «اليوم»، «أمس»، ثم تاريخ.
  • بلا علامات ترقيم في نهاية العناوين.

تجنّب

  • بدء العناوين بحشو: «لقد استلمت…».
  • الجمع بين جمل كاملة وعبارات ناقصة في قائمة واحدة.
  • عرض معرّفات خام حيث يتوقع الناس أسماء.

4. إجراءات السحب

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

افعل

  • إجراء بادئ واحد وإجراءان لاحقان على الأكثر.
  • لوّن حسب المعنى: العلامة للإيجابي، والتحذير للأرشفة أو التأجيل، والخطر للحذف.
  • أعطِ كل إجراء أيقونة وتسمية قصيرة.
  • قدّم الإجراءات نفسها في قائمة الصف أو في شاشة التفاصيل.
  • قدّم «تراجع» في إشعار بعد الحذف أو الأرشفة.

تجنّب

  • إخفاء إجراء خلف السحب وحده.
  • وضع «حذف» في الجهة البادئة، حيث تطلقه سحبة سريعة.
  • السحب على الحاسوب، حيث لا يستطيع الناس السحب؛ اعرض قائمة الصف.
  • إضافة إجراء لاحق ثالث.

5. الحالات والتحميل والقوائم الطويلة

الصف كله منطقة ضغط واحدة: الضغط عليه يفتح السجل. واستخدم حالة التمرير على الأجهزة ذات المؤشر. واعرض صفوف الهيكل أثناء التحميل، والحالة الفارغة حين لا يكون هناك ما يُعرض. وحمّل القوائم الطويلة صفحاتٍ أو مع التمرير.

افعل

  • اجعل الصف كله يفتح السجل.
  • صفوف هيكل بارتفاع الصف أثناء التحميل.
  • حالة فارغة بخطوة تالية حين تكون القائمة فارغة.
  • جمّع القوائم الطويلة حسب اليوم برأس قسم.

تجنّب

  • زر منفصل في الصف للإجراء الرئيسي.
  • مؤشر تحميل مكان القائمة كلها.
  • تحميل آلاف الصفوف دفعة واحدة.

6. العربية والاتجاه من اليمين إلى اليسار

استخدم النسخة العربية في القوائم العربية. ينتقل العنصر البادئ إلى اليمين والوسم إلى اليسار، وتنعكس جهتا السحب: يُكشف الإجراء البادئ من اليمين. وتبقى الأوقات والمبالغ وأرقام الهواتف داخل الصف تُقرأ من اليسار إلى اليمين.

الصفوف تبدأ من اليمين

قائمة نشاط المدفوعات بالعربية.

افعل: النسخة العربيةالصورة الرمزية على اليمين والنص يحاذي اليمين، بالخطوط وارتفاعات الأسطر العربية.
تجنّب: النسخة الإنجليزية بنص عربيتبقى الصورة الرمزية على اليسار، والنص بالخطوط اللاتينية.

قبل التسليم

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

إمكانية الوصول

لوحة المفاتيح

المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.

المفتاحما يفعله
Tabإلى الصفوف التفاعلية وزر ⋮ في كل صف قابل للسحب.
Enterيفتح الرابط أو يضغط الصف أو يفتح قائمة الإجراءات.

ARIA

  • القائمة ul وكل صف li، فيعلن قارئ الشاشة عدد العناصر.
  • الصورة الرمزية بجانب الاسم زخرفية (decorative)، كي لا يُقرأ الاسم مرتين.
  • الصف المعطّل زر disabled أو رابط aria-disabled بلا وجهة، فيُعلَن معطّلًا ولا يُفعَّل. نص التعطيل معفى من حد التباين، فاكتب السبب واضحًا.
  • السحب ليس الطريق الوحيد: زر ⋮ يعرض الإجراءات نفسها. وبدونه (menu={false}) تصبح أزرار الإجراءات قابلة للتركيز ويفتح الصف عند التركيز عليها.
  • الصف المفتوح يُغلق عند اللمس أو التركيز خارجه.

افعل

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

تجنّب

  • وضع عدة أزرار داخل رابط صف واحد.
  • الاعتماد على لون إجراء السحب لشرحه.

ملاحظات العربية والاتجاه

ينعكس

  • الصورة الرمزية أو الأيقونة على اليمين، والوسم وزر ⋮ على اليسار.
  • السحب يتبع اتجاه القراءة: في العربية السحب لليسار يكشف إجراءات البداية (على اليمين)، والسحب لليمين يكشف إجراءات النهاية.

لا ينعكس

  • أيقونات الإجراءات (أرشفة، ساعة، سلة) والصور الرمزية.
الأرقام
الأرقام في النصوص كما تمرّرها؛ نسّقها بـ formatNumber.
الخط العربي
العنوان body-16 Medium، والنص المساعد body-12، والسطر العلوي label-12. الصف 70 بكسل على الأقل، فالنصوص العربية الأطول تكبّره بدل أن تُقص.
النص ثنائي الاتجاه
أسماء بلغة أخرى داخل النص العربي تُعزل بـ <bdi>.

افعل

  • النسخة العربية لكل صف في قائمة عربية.
  • اعكس جهتي السحب: الجهة البادئة على اليمين في العربية.
  • أبقِ الأوقات والمبالغ من اليسار إلى اليمين داخل النص العربي.
  • اكتب العناوين بالعربية أصلًا.

تجنّب

  • نص عربي في النسخة الإنجليزية.
  • إبقاء جهتي السحب الإنجليزيتين في قائمة عربية.

الفحوص التي يجتازها

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

  • R042نص مقصوص: محتوى أعرض من صندوقه مع overflow مخفي وبلا علامة حذف
  • R043حاوية بعرض ثابت بالبكسل يتجاوز نصها العربي المساحة
  • R050نص عربي يسقط إلى خط غير الخط المعلن (مقيسًا، أو وفق الإعلان، أو لأن خط الويب فشل في التحميل)
  • R051تباعد حروف مطبَّق على نص عربي (يكسر الخط المتصل)