زر القائمة
زر يفتح قائمة إجراءات: إجراءات الصف، والحساب، والإجراءات الثانوية. القائمة تفتح أسفل الزر عند بداية السطر، أي على اليمين في العربية.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add menuويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/menuالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { DotsThreeVerticalIcon, PencilSimpleIcon } from "@phosphor-icons/react/ssr";import { IconButton } from "@/components/ui/icon-button";import { Menu, MenuContent, MenuItem, MenuTrigger } from "@/components/ui/menu";<Menu> <MenuTrigger render={<IconButton variant="outline" icon={DotsThreeVerticalIcon} label="Invoice actions" />} /> <MenuContent> <MenuItem leadingIcon={PencilSimpleIcon} onClick={edit}>Edit</MenuItem> <MenuItem onClick={duplicate}>Duplicate</MenuItem> </MenuContent></Menu>أمثلة
زر منقسم
نوع Button في Figma: نصف القائمة في الزر المنقسم يفتح القائمة نفسها، وتصطف القائمة مع الزر كله.
قائمة الصورة الشخصية
نوع Avatar menu في Figma: صورة الحساب تفتح قائمة الحساب. الزر دائري ويُسمّى بما يفتحه («قائمة الحساب»)، والصورة داخله زخرفية فلا يُقرأ الاسم مرتين.
الأقسام والفواصل
MenuGroup مع MenuLabel يسمّي كل قسم، وMenuSeparator بين الأقسام. description يضيف سطرًا ثانيًا، وMenuLinkItem للتنقل، والعنصر المعطّل يبقى ظاهرًا مع سببه.
اختيارات
حالة Selected: MenuRadioGroup وMenuRadioItem لاختيار واحد، وMenuCheckboxItem لعدة اختيارات. الصف المختار بلون brand/faint مع علامة صح في نهاية السطر (اليسار في العربية) لا تنعكس، والقائمة تبقى مفتوحة. subtitle ملاحظة قصيرة بجانب العنوان، وbadge عدد في النهاية.
إجراء خطِر
حالة Danger: danger يلوّن العنوان والوصف والأيقونة بالأحمر. ضعه أخيرًا في مجموعته، واجعل العنوان يقول ما يفعله. trailingIcon أيقونة في النهاية، هنا لما يفتح موقعًا آخر.
مرجع الخصائص
Menu
الجذر: يحمل الحالة (open، onOpenChange، disabled، modal).
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
open / defaultOpen | boolean | لا يوجد | فتح القائمة (متحكَّم به أو لا). |
onOpenChange | (open: boolean) => void | لا يوجد | يُستدعى عند الفتح والإغلاق. |
disabled | boolean | false | يعطّل الزر والقائمة. |
MenuTrigger
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
render | ReactElement | لا يوجد | الزر الظاهر: <IconButton … /> أو <Button … />. يأخذ aria-haspopup وaria-expanded. |
MenuContent
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
align | "start" | "center" | "end" | "start" | المحاذاة مع الزر؛ في Figma عند بداية السطر. |
sideOffset | number | 12 | المسافة تحت الزر بالبكسل. |
anchor | "trigger" | "parent" | "trigger" | ما تصطف معه القائمة؛ parent للزر المنقسم كله. |
MenuItem, MenuLinkItem, MenuSubmenuTrigger
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
children | ReactNode | لا يوجد | العنوان (Title). |
leadingIcon | IconComponent | لا يوجد | Show leading: أيقونة 24 بكسل في بداية السطر. |
description | ReactNode | لا يوجد | Show description: سطر ثانٍ تحت العنوان. |
subtitle | ReactNode | لا يوجد | Show subtitle: ملاحظة قصيرة بجانب العنوان. |
badge | ReactNode | لا يوجد | Show badge: عدد أو كلمة في نهاية السطر، لا يخفت مع التعطيل. نسّق الأرقام بـ formatNumber. |
trailingIcon | IconComponent | لا يوجد | Show trailing: أيقونة في نهاية السطر (MenuItem وMenuLinkItem). |
danger | boolean | false | State = Danger في MenuItem: إجراء يحذف أو يزيل. |
onClick | (event) => void | لا يوجد | MenuItem: يُستدعى عند الاختيار ثم تُغلق القائمة. |
href | string | لا يوجد | MenuLinkItem: وجهة الرابط. |
disabled | boolean | false | State = Disabled؛ يبقى ظاهرًا ويتلقى التركيز ولا يُنفَّذ. اكتب السبب في description. |
MenuRadioGroup, MenuRadioItem, MenuCheckboxItem
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
value / defaultValue / onValueChange | string | لا يوجد | MenuRadioGroup: الاختيار الحالي. |
value | string | لا يوجد | MenuRadioItem: قيمة هذا الاختيار. |
checked / defaultChecked / onCheckedChange | boolean | لا يوجد | MenuCheckboxItem: مفعّل أم لا. |
leadingIcon / subtitle / description / badge | … | لا يوجد | كما في MenuItem. |
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| EnterSpaceArrowDown | على الزر: يفتح القائمة ويركّز العنصر الأول. |
| ArrowDownArrowUp | ينتقل بين العناصر ويلتف عند الطرفين. العنصر المعطّل يتلقى التركيز ليُقرأ سببه، لكنه لا يُنفَّذ. |
| ArrowRightArrowLeft | يفتح القائمة الفرعية ويغلقها. في العربية ينعكس: السهم الأيسر يفتح. |
| Enter | ينفّذ العنصر المركّز ويغلق القائمة. |
| SpaceEnter | على اختيار: يختاره أو يبدّله، وتبقى القائمة مفتوحة. |
| Escape | يغلق القائمة ويعيد التركيز إلى الزر. |
ARIA
- الزر يحمل
aria-haspopup="menu"وaria-expanded، والقائمةrole="menu"وعناصرهاmenuitem. - زر الأيقونة يحتاج
labelيصف ما تحويه القائمة («إجراءات الفاتورة»)، لا «المزيد». MenuLabelيسمّي مجموعته، فتعلن قارئات الشاشة اسم القسم.- الاختيارات
menuitemradioوmenuitemcheckboxمعaria-checked، فلا يعتمد الاختيار على اللون والعلامة وحدهما. العلامة مخفية عن قارئ الشاشة.
ملاحظات العربية والاتجاه
ينعكس
- القائمة تفتح عند بداية الزر (اليمين في العربية)، والقوائم الفرعية نحو نهاية السطر (اليسار).
- سهم القائمة الفرعية
CaretRightينعكس، والأسهم على لوحة المفاتيح تتبع اتجاه القراءة. - القائمة تأخذ اتجاه الزر ولغته، حتى داخل جزيرة عربية في صفحة إنجليزية.
لا ينعكس
DotsThreeVerticalوالأيقونات غير الاتجاهية لا تنعكس.- علامة الصح في الصف المختار لا تنعكس، وإن كانت في نهاية السطر.
- سهم الزر المنقسم يشير إلى الأسفل ويستدير إلى الأعلى ما دامت القائمة مفتوحة، ولا ينعكس.
- الأرقام
- الأعداد في الأسطر الثانية («8 أعضاء») تُنسّق بـ
formatNumber؛ المعرّفات («INV-1042») في<bdi dir="ltr">ولا تتغير. - الخط العربي
- العنوان
label-14بوزن Medium، والسطر الثانيlabel-12، وعنوان القسمbody-14Semibold. الصفوف 48 بكسل وتتسع للعربية. - النص ثنائي الاتجاه
- اسم لاتيني في نهاية عنصر عربي («تنزيل PDF») يُعرض صحيحًا؛ في وسطه ضعه في
<bdi>.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.