قائمة الأوامر
ابحث عن أي أمر وشغّله من أي مكان بلوحة المفاتيح. تفتحها ⌘K أو Ctrl+K، وتفهم أشكال الحروف العربية التي يكتبها الناس بطرق مختلفة.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add commandويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/commandالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { CommandDialog } from "@/components/ui/command";<CommandDialog trigger={<Button variant="outline" />} triggerLabel="Search commands" groups={[ { heading: "Suggestions", items: [{ value: "transfer", label: "New transfer", icon: ArrowsLeftRightIcon, onSelect: newTransfer }] }, ]}/>أمثلة
أشخاص بسطرين
Command داخل الصفحة بلا نافذة: صور رمزية، والمعرّف تحت الاسم (stacked)، ويُبحث فيه أيضًا.
نقاط الحالة
dot لحالة كل صف، والحالة مكتوبة بجانبه فلا يكون اللون وحده الدليل. الحجم md، والصف المتوقف disabled.
بحث يفهم العربية
اكتب «اضافه» فتجد «إضافة بطاقة»، و«فاتوره» فتجد «دفع الفاتورة»: البحث يوحّد الهمزات والتاء المربوطة والألف المقصورة ويتجاهل التشكيل والتطويل، والأرقام الهندية تطابق العربية. وkeywords تضيف أسماء إنجليزية: «invoice». واكتب ما لا يوجد لترى حالة «لا نتائج».
مرجع الخصائص
Command
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
groups | { heading?: string; items: CommandItemData[] }[] | لا يوجد | الأقسام وصفوفها. |
size | "sm" | "md" | "sm" | خاصية Size للصفوف. |
stacked | boolean | false | خاصية Text = Stacked: النص المساعد تحت الاسم. |
label / placeholder | string | "Search commands" / "Search" | اسم حقل البحث ونصه المؤقت، بلغة المكان افتراضيًا. |
empty | ReactNode | لا يوجد | ما يظهر حين لا يطابق شيء. |
footer / footerAction | boolean / ReactNode | true | تلميحات المفاتيح، وزر في نهايتها. |
onSelect | (item) => void | لا يوجد | يعمل بعد onSelect الخاص بالصف. |
CommandItemData
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
value / label | string | لا يوجد | معرّف الصف ونصه. |
supportingText | string | لا يوجد | خاصية Supporting text، ويُبحث فيها. |
icon / avatar / dot | IconComponent / ReactNode / "green" | "amber" | "red" | "brand" | "gray" | لا يوجد | خاصية Type: أيقونة أو صورة رمزية أو نقطة حالة. |
shortcut | string[] | لا يوجد | اختصار الأمر في التطبيق، للعرض فقط. |
keywords | string[] | لا يوجد | كلمات أخرى تجد الصف، كالأسماء الإنجليزية. |
onSelect / disabled | () => void / boolean | لا يوجد | ما يحدث عند الاختيار. |
CommandDialog
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
trigger / triggerLabel | ReactElement / ReactNode | لا يوجد | الزر الذي يفتحها ونصه. |
shortcut | boolean | true | ⌘K على ماك وCtrl+K على غيره، على مفتاح K نفسه في أي لغة لوحة مفاتيح. |
open / defaultOpen / onOpenChange | boolean | لا يوجد | للتحكم في الفتح. |
title | string | "Command menu" | اسم النافذة لقارئ الشاشة. |
… | CommandProps | لا يوجد | كل خصائص Command. |
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| ⌘KCtrl+K | يفتح القائمة ويغلقها من أي مكان. |
| ArrowDownArrowUp | بين الصفوف، والتركيز يبقى في حقل البحث. |
| Enter | يشغّل الصف المحدد ويغلق النافذة. |
| Esc | يغلق النافذة ويعيد التركيز. |
ARIA
- حقل البحث
comboboxيتحكم فيlistbox، والصف المحدد يُعلن بـaria-activedescendant. - الأقسام مجموعات لها عناوين، والنافذة لها اسم («قائمة الأوامر»).
- نقاط الحالة مصحوبة بكلمة، وتلميحات المفاتيح تكرار لما يعلنه قارئ الشاشة فهي مخفية عنه.
ملاحظات العربية والاتجاه
ينعكس
- الأيقونات والصور الرمزية على اليمين، والاختصارات على اليسار، وعناوين الأقسام تبدأ من اليمين.
- تكتب في الحقل بأي لغة فيتبعها اتجاه النص (
dir="auto").
لا ينعكس
- مفاتيح الاختصار (⌘ T) تبقى من اليسار إلى اليمين كما على لوحة المفاتيح، ورمز مفتاح الإدخال لا ينعكس.
- سهما الأعلى والأسفل.
- الأرقام
- الأرقام الهندية في البحث تطابق العربية: «٣» تجد «3».
- الخط العربي
- النص
body-14(وbody-16في الحجمmd) ونص الحقلbody-16، والصفوف تكبر مع الأسطر العربية. - النص ثنائي الاتجاه
- ⌘K يعمل على مفتاح K نفسه ولو كانت لوحة المفاتيح عربية (حيث يكتب «ن»).
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.
- نصوص سمات غير مترجمة (placeholder وalt وtitle وaria-label وقيمة الزر)
- نص مقصوص: محتوى أعرض من صندوقه مع overflow مخفي وبلا علامة حذف
- حاوية بعرض ثابت بالبكسل يتجاوز نصها العربي المساحة
- نص عربي يسقط إلى خط غير الخط المعلن (مقيسًا، أو وفق الإعلان، أو لأن خط الويب فشل في التحميل)
- تباعد حروف مطبَّق على نص عربي (يكسر الخط المتصل)