القائمة
صفوف متتالية لأشخاص أو رسائل أو إعدادات: عنوان مع سطر علوي ونص مساعد، وصورة رمزية أو أيقونة في البداية، ووسم في النهاية. والصف القابل للسحب يكشف إجراءات عند سحبه.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add listويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/listالاعتماديات التي يضيفها
@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
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)، فتظهر خلفية المرور عليها.
صف قابل للسحب
اسحب نحو النهاية للأرشفة، ونحو البداية للتأجيل أو الحذف. البداية والنهاية تتبعان اتجاه القراءة. وزر ⋮ يعرض الإجراءات نفسها للوحة المفاتيح وقارئ الشاشة والفأرة.
روابط وصف ثابت
href أو render={<Link />} يجعل الصف رابطًا. والصف بلا رابط ولا onClick ثابت، بلا خلفية عند المرور.
صف معطّل
disabled يلوّن النص بلون التعطيل ويخفف العنصرين في البداية والنهاية إلى 48%، ويزيل التمرير. صف الزر يصبح زرًا معطّلًا، وصف الرابط يفقد وجهته. قل السبب في النص المساند.
مرجع الخصائص
List
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
aria-label | string | لا يوجد | اسم القائمة إن كان في الصفحة أكثر من قائمة. |
children | ReactNode | لا يوجد | عناصر ListItem أو SwipeableListItem. |
ListItem
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
children | ReactNode | لا يوجد | خاصية Headline. |
overline | ReactNode | لا يوجد | خاصية Overline: سطر قصير فوق العنوان. |
supportingText | ReactNode | لا يوجد | خاصية Supporting text تحت العنوان. |
leading | ReactNode | لا يوجد | عنصر البداية: صورة رمزية أو علم أو صورة. |
leadingIcon | IconComponent | لا يوجد | أيقونة في دائرة 40 بكسل (النوع Icon). |
trailing | ReactNode | لا يوجد | خاصية Show Tags: وسم أو أي عنصر في النهاية. |
href | string | لا يوجد | يجعل الصف رابطًا. |
render | ReactElement | لا يوجد | رابط التوجيه (<Link>) بمظهر الصف. |
onClick | MouseEventHandler | لا يوجد | يجعل الصف زرًا. |
disabled | boolean | false | خاصية State = Disabled. في السحب: لا سحب، وزر ⋮ معطّل. |
SwipeableListItem
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
leadingActions | SwipeAction[] | لا يوجد | إجراءات تظهر في البداية عند السحب نحو النهاية (Swipe = Leading). |
trailingActions | SwipeAction[] | لا يوجد | إجراءات تظهر في النهاية عند السحب نحو البداية (Swipe = Trailing). |
SwipeAction | { label, icon, tone?: "brand" | "warning" | "danger", onAction } | لا يوجد | إجراء واحد بعرض 88 بكسل. |
menu | boolean | true | زر ⋮ بالإجراءات نفسها، كي لا يكون السحب الطريق الوحيد. |
menuLabel | string | "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-16Medium، والنص المساعدbody-12، والسطر العلويlabel-12. الصف 70 بكسل على الأقل، فالنصوص العربية الأطول تكبّره بدل أن تُقص. - النص ثنائي الاتجاه
- أسماء بلغة أخرى داخل النص العربي تُعزل بـ
<bdi>.
افعل
- النسخة العربية لكل صف في قائمة عربية.
- اعكس جهتي السحب: الجهة البادئة على اليمين في العربية.
- أبقِ الأوقات والمبالغ من اليسار إلى اليمين داخل النص العربي.
- اكتب العناوين بالعربية أصلًا.
تجنّب
- نص عربي في النسخة الإنجليزية.
- إبقاء جهتي السحب الإنجليزيتين في قائمة عربية.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.