الجدول
صفوف من السجلات يقارنها المستخدم ويتصرف بناءً عليها: معاملات وطلبات ومستخدمون. جدول حقيقي بعناوين أعمدة وخلايا.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add tableويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/tableالاعتماديات التي يضيفها
@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";<Table> <TableHeader variant="gray"> <TableRow> <TableHead sort="descending" onSort={toggle}>Date</TableHead> <TableHead align="end">Amount</TableHead> </TableRow> </TableHeader> <TableBody> <TableRow> <TableCell>12/09/2026</TableCell> <TableCell numeric>+2,450.00 JOD</TableCell> </TableRow> </TableBody></Table>أمثلة
تحديد الصفوف
مربع تفعيل في أول عمود (CheckboxBox باسمه)، وصورة رمزية ونص فرعي في الخلية؛ الصف المحدد يبقى ملوّنًا.
عنوان أبيض وتلميح
variant="white" (الافتراضي)، وأيقونة قبل العنوان، وتلميح معلومات، ودون فواصل الأعمدة (dividers={false}).
جدول بيانات
شريط أدوات (بحث وتصفية وتصدير)؛ ومربع «تحديد الكل» داخل خلية العنوان عبر leading؛ وTableSelectionBar للإجراءات الجماعية مع عدد يُعلن بأرقام الصفحة؛ وإجراءات الصف في آخر خلية (اثنان ظاهران على الأكثر والباقي في «المزيد»، وكل زر يسمّي صفه)؛ وTablePagination تحت الجدول.
صفوف قابلة للتوسيع
TableExpandToggle في أول خلية يفتح TableExpandedRow تحت صفه، بعد عمود الزر. أبقِ الصف المغلق بـhidden كي يصل إليه البحث في الصفحة.
أعمدة ثابتة
sticky="start" يُبقي أول عمود ظاهرًا، وsticky="end" عمود الإجراءات، على TableHead وTableCell معًا. يظهر الظل حين يمرّ شيء تحته فقط. مرّر الجدول أفقيًا.
مرجع الخصائص
Table
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
dividers | boolean | true | خاصية Show divider: خط عند نهاية كل عمود. |
aria-label / TableCaption | string / ReactNode | لا يوجد | اسم الجدول لقارئ الشاشة. |
TableHeader
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
variant | "white" | "gray" | "white" | خاصية Color في Table header cell. |
TableRow
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
selected | boolean | false | State = Hover/selected ثابتة لصف محدد. |
TableHead
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
children | ReactNode | لا يوجد | خاصية Label. |
sort | "none" | "ascending" | "descending" | لا يوجد | عمود قابل للترتيب وحالته؛ اتركه للأعمدة الأخرى. |
onSort / sortHref | () => void / string | لا يوجد | زر ترتيب (شيفرة العميل) أو رابط (صفحات الخادم). |
leadingIcon | IconComponent | لا يوجد | خاصية Leading icon. |
info | ReactNode | لا يوجد | خاصية Show tooltip: تلميح معلومات بعد العنوان. |
align | "start" | "end" | "start" | end لأعمدة الأرقام. |
leading | ReactNode | لا يوجد | خاصية Show checkbox: عنصر تحكم قبل العنوان (مربع «تحديد الكل»)، خارج زر الترتيب. |
sticky | "start" | "end" | لا يوجد | يُبقي العمود ظاهرًا أثناء التمرير الأفقي. |
TableCell
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
children | ReactNode | لا يوجد | خاصية Cell Title. |
subtitle | ReactNode | لا يوجد | خاصية Cell Subtitle. |
leading / trailing | ReactNode | لا يوجد | العنصر قبل النص وبعده: صورة رمزية، أيقونة، وسم، مربع تفعيل… |
numeric | boolean | false | مبلغ أو عدد: في نهاية العمود بأرقام متساوية العرض، ومن اليسار إلى اليمين. |
sticky | "start" | "end" | لا يوجد | مثل TableHead؛ ضعه على الاثنين. |
TableSelectionBar
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
count | number | لا يوجد | عدد الصفوف المحددة؛ اعرض الشريط ما دام أكبر من صفر. |
onClear | () => void | لا يوجد | زر «إلغاء التحديد»؛ بدونه يختفي الزر. |
clearLabel / countLabel | ReactNode / (n) => ReactNode | لا يوجد | بدل النصين الافتراضيين («تم تحديد ٣»). |
children | ReactNode | لا يوجد | الإجراءات الجماعية: أزرار Ghost sm، والحذف بـdanger. |
TableExpandToggle
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
expanded | boolean | لا يوجد | هل التفاصيل ظاهرة. |
onExpandedChange | (expanded: boolean) => void | لا يوجد | يُستدعى بالحالة التالية. |
controls | string | لا يوجد | معرّف TableExpandedRow. |
label | string | لا يوجد | اسم الزر يسمّي الصف («تفاصيل عمر حداد»)؛ والحالة في aria-expanded. |
TableExpandedRow
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
id | string | لا يوجد | المعرّف الذي يشير إليه الزر. |
colSpan | number | لا يوجد | عدد أعمدة الجدول. |
TablePagination
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
pageCount | number | لا يوجد | عدد الصفحات. |
page / defaultPage / onPageChange | number / number / (page) => void | لا يوجد | الصفحة الحالية، من 1. |
pageSize / defaultPageSize / onPageSizeChange | number / number / (size) => void | لا يوجد | الصفوف في الصفحة. |
pageSizes | number[] | [10, 20, 50] | الخيارات في القائمة. |
selected / total | number | لا يوجد | «تم تحديد 2 من 248 صفًا»؛ اتركهما لإخفائه. |
numerals | "latn" | "arab" | لا يوجد | نظام الأرقام؛ الافتراضي من RitlaProvider. |
إرشادات الاستخدام
الجدول يقارن الحقائق نفسها عبر سجلات كثيرة. هنا: الجدول أم القائمة أم البطاقات، ومحاذاة النصوص والأرقام، والرؤوس والترتيب، وما يحمله الصف، والشاشات الصغيرة، وانعكاسه في العربية، وما تتحقق منه قبل التسليم.
1. جدول أم قائمة أم بطاقات
استخدم الجدول حين يقارن الناس الحقائق نفسها عبر سجلات كثيرة ويتصرفون بناءً عليها: تواريخ، ومبالغ، وحالات. وحين يُقرأ كل سجل وحده، أو تكون الشاشة ضيقة، فالقائمة أو البطاقات أنسب.
| تحتاج إلى | استخدم | السبب |
|---|---|---|
| مقارنة الحقول نفسها عبر سجلات كثيرة | جدول | الأعمدة تسهّل المقارنة والترتيب. |
| قراءة السجلات واحدًا واحدًا، بعنوان وملخص | قائمة | كل صف قصة صغيرة، لا مجموعة حقول. |
| عرض بضعة عناصر غنية بالصور | بطاقات | العناصر المرئية لا تتسع في الخلايا. |
| عرض السجلات على هاتف | قائمة، أو جدول يتحول إلى بطاقات | الأعمدة لا تتسع في شاشة ضيقة. |
2. محاذاة النصوص والأرقام
يحاذي النص بداية السطر. والمبالغ وغيرها من الأرقام التي يقارنها الناس تصطف عند الفواصل العشرية، بعدد المنازل العشرية نفسه في كل صف، فتصطف الأرقام حسب منازلها. واستخدم صيغة تاريخ واحدة وصيغة عملة واحدة في الجدول كله.
المبالغ تصطف عند النهاية
معاملات البطاقة.
افعل
- حاذِ المبالغ والأعداد إلى اليمين لتصطف الفواصل العشرية.
- المنازل العشرية وصيغة العملة نفسها في العمود.
- صيغة تاريخ واحدة في الجدول.
- خلايا العمود بالعرض نفسه.
تجنّب
- محاذاة المبالغ إلى البداية، فلا يصطف 85.500 و12,400.000.
- الجمع بين 1.2k و1,200 في عمود واحد.
- توسيط أعمدة النص.
3. الرؤوس والترتيب
لكل عمود رأس قصير. واعرض أيقونة الترتيب فقط على الأعمدة القابلة للترتيب، مع الاتجاه الحالي على العمود المرتّب. وضع مربع «تحديد الكل» في أول رأس حين يمكن تحديد الصفوف.
افعل
- الرؤوس كلمة أو كلمتان.
- أيقونة الترتيب على الأعمدة القابلة للترتيب فقط.
- رتّب افتراضيًا بالعمود الأنفع، غالبًا التاريخ، الأحدث أولًا.
تجنّب
- أيقونة ترتيب على كل عمود.
- رؤوس تلتف إلى سطرين.
- ترك الناس لا يعرفون بأي عمود رُتّب الجدول.
4. ما يحمله الصف
قيمة رئيسية واحدة في كل خلية، مع عنوان فرعي اختياري. والحالات في وسوم، والأشخاص بصورة رمزية واسم، وإجراءات الصف في قائمة عند نهاية السطر. وصمّم الجدول الفارغ وصفوف التحميل وحالة الخطأ، وضع ترقيم الصفحات تحت الجدول.
افعل
- الحالات في وسوم، والأشخاص بصور رمزية وأسماء.
- إجراءات الصف في زر قائمة عند نهاية السطر.
- صمّم حالات الفراغ والتحميل والخطأ.
- ضع ترقيم الصفحات وعدد النتائج تحت الجدول.
تجنّب
- عدة أزرار في كل صف.
- عرض رموز خام حيث يتوقع الناس أسماء.
- عرض شبكة فارغة بلا رسالة.
5. الشاشات الصغيرة
الجداول تحتاج إلى عرض. على الأجهزة اللوحية دع الجدول يتمرّر أفقيًا وثبّت العمود الأول. وعلى الهواتف حوّل كل صف إلى عنصر قائمة أو بطاقة تُظهر الحقلين أو الثلاثة الأهم.
افعل
- ثبّت العمود الأول وتمرّر البقية أفقيًا.
- انتقل إلى عناصر قائمة أو بطاقات على الهواتف.
- ترتيب الحقول نفسه في التخطيطين.
تجنّب
- حشر كل الأعمدة في شاشة هاتف.
- إخفاء أعمدة مهمة دون وسيلة لرؤيتها.
6. العربية والاتجاه من اليمين إلى اليسار
استخدم الخلايا العربية في الجداول العربية: العمود الأول على اليمين والنص يحاذي اليمين. والمبالغ لا تنعكس: أرقامها تُقرأ من اليسار إلى اليمين، فتبقى محاذية لليمين وتصطف عند الفواصل العشرية، مثل المحور الرقمي في رسم بياني. ولا تجمع بين خلايا إنجليزية وعربية في جدول واحد أبدًا.
الأعمدة تنعكس، والمبالغ لا
معاملات البطاقة بالعربية.
قبل التسليم
- النص يحاذي البداية، والمبالغ تصطف عند الفواصل، والصيغ متطابقة.
- الأعمدة القابلة للترتيب والترتيب الافتراضي معلَّمة.
- الفراغ والتحميل والخطأ وترقيم الصفحات مصمّمة.
- تخطيط الهاتف مصمّم.
- الجداول العربية تستخدم الخلايا العربية فقط.
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| Tab | إلى أزرار الترتيب وعناصر التحكم داخل الخلايا فقط. |
| EnterSpace | يرتّب العمود. |
ARIA
- جدول حقيقي:
tableوth scope="col"وtd، وقارئ الشاشة يربط كل خلية بعنوانها. - العمود القابل للترتيب زر داخل
thالذي يحملaria-sort. - مربعات التحديد لها أسماء («تحديد الكل»، اسم الصف).
- شريط التحديد منطقة اسمها «التحديد»، وعدده يُعلن بلطف حين يتغيّر.
- زر التوسيع يحمل
aria-expandedوaria-controls، واسمه ثابت يسمّي الصف. - ترقيم الجدول عنصر
navباسمه؛ أزرار الأطراف تبقى قابلة للتركيز وهي معطّلة، فلا يضيع التركيز في الصفحة الأولى، و«الصفحة 1 من 25» يُعلن بلطف.
افعل
- خلية رأس لكل عمود.
aria-sortعلى العمود المرتّب.- سمِّ مربع اختيار الصف باسم الصف: «تحديد Cozmo، 3 مارس».
- عنوان ظاهر للجدول أو
caption.
تجنّب
- بناء الجداول من صناديق عامة بدل ترميز الجدول.
- الاعتماد على اللون وحده للمبالغ السالبة؛ أضف علامة الناقص.
ملاحظات العربية والاتجاه
ينعكس
- أول عمود على اليمين، والنص في بداية الخلية (يمينها)، والفاصل في نهايتها (يسارها).
- أعمدة الأرقام في نهاية الخلية (يسارها في العربية).
- العمود الثابت
startعلى اليمين وظله إلى يساره؛ وزر التوسيع يشير إلى اليسار وهو مغلق؛ وأسهم الترقيم تنقلب («التالية» إلى اليسار).
لا ينعكس
- المبالغ تبقى من اليسار إلى اليمين، فتبقى الإشارة بجانب الرقم.
- البريد الإلكتروني والأرقام التعريفية في
<bdi dir="ltr">.
- الأرقام
- التواريخ والمبالغ بنظام الأرقام المختار؛ لا تخلط الصيغ في العمود الواحد. عدد التحديد والترقيم بأرقام الصفحة، و«صف» يتّفق مع العدد (٣ صفوف، ١١ صفًا، ١٠٠ صف).
- الخط العربي
-
body-12بوزن Semibold للعناوين، وbody-14بوزن Medium للخلايا، وbody-12للنص الفرعي. - النص ثنائي الاتجاه
- لا تخلط خلايا LTR وRTL في جدول واحد: الاتجاه يأتي من الصفحة.
افعل
- خلايا الرأس والخلايا بالنسخة العربية في الجدول كله.
- تبدأ الأعمدة من اليمين، بترتيب الإنجليزية نفسه.
- أبقِ المبالغ محاذية لليمين كي تصطف الفواصل العشرية، فالأرقام تُقرأ من اليسار إلى اليمين.
- اكتب العملة في رأس العمود حين يشترك فيها العمود كله.
- أبقِ الأرقام وأرقام الآيبان والرموز من اليسار إلى اليمين داخل خلاياها.
تجنّب
- الجمع بين خلايا إنجليزية وعربية في جدول واحد.
- عكس أعمدة المبالغ إلى اليسار، فلا تعود المنازل تصطف.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.
- مخاطر اتجاه غير معزولة: أرقام هواتف وبريد إلكتروني ومقاطع لاتينية داخل نص عربي
- text-align: left مضبوطة صراحة على نص عربي في معظمه
- نص مقصوص: محتوى أعرض من صندوقه مع overflow مخفي وبلا علامة حذف
- حاوية بعرض ثابت بالبكسل يتجاوز نصها العربي المساحة
- نص عربي يسقط إلى خط غير الخط المعلن (مقيسًا، أو وفق الإعلان، أو لأن خط الويب فشل في التحميل)
- تباعد حروف مطبَّق على نص عربي (يكسر الخط المتصل)