لوحة أوامر

Command

لوحة أوامر في React مبنية على cmdk ببحث تقريبي ومجموعات واختصارات وCommandDialog يربط Cmd+K وCtrl+K. تعمل مضمّنة أو منبثقة.

افتح في ستوري بوك ↗

يعرض Command الإجراءات خلف حقل بحث، وينفذ كل CommandItem حدث onSelect. أما CommandDialog فهو اللوحة نفسها داخل نافذة ويتكفل باختصار ⌘K.

متى تستخدمه

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

للبحث في المحتوى لا الأوامر، استخدم SearchBox.

أمثلة

لوحة مضمّنة

قائمة الأوامر

حوار ⌘K

اضغط ⌘K (أو Ctrl+K) في أي مكان.

اختصار مخصّص

الخصائص

الخصائص التي يعرّفها Command. سمات العنصر الأصلي تمرّ كما هي.

<Command>

الخاصية	النوع	الوصف
`children`	`ReactNode`
`asChild`	`boolean`
`label`	`string`	Accessible label for this command menu. Not shown visibly.
`shouldFilter`	`boolean`	Optionally set to `false` to turn off the automatic filtering and sorting. If `false`, you must conditionally render valid items based on the search query yourself.
`filter`	`CommandFilter`	Custom filter function for whether each command menu item should matches the given search query. It should return a number between 0 and 1, with 1 being the best match and 0 being hidden entirely. By default, uses the `command-score` library.
`defaultValue`	`string \| (readonly string[] & string)`	Optional default item value when it is initially rendered.
`value`	`string`	Optional controlled state of the selected command menu item.
`onValueChange`	`(value: string) => void`	Event handler called when the selected item of the menu changes.
`loop`	`boolean`	Optionally set to `true` to turn on looping around when using the arrow keys.
`disablePointerSelection`	`boolean`	Optionally set to `true` to disable selection via pointer events.
`vimBindings`	`boolean`	Set to `false` to disable ctrl+n/j/p/k shortcuts. Defaults to `true`.

<CommandInput>

الخاصية	النوع	الوصف
`asChild`	`boolean`
`value`	`string`	Optional controlled state for the value of the search input.
`onValueChange`	`(search: string) => void`	Event handler called when the search value changes.

<CommandList>

الخاصية	النوع	الوصف
`children`	`ReactNode`
`asChild`	`boolean`
`label`	`string`	Accessible label for this List of suggestions. Not shown visibly.

<CommandEmpty>

الخاصية	النوع	الافتراضي	الوصف
`children`	`ReactNode`
`asChild`	`boolean`

<CommandGroup>

الخاصية	النوع	الوصف
`children`	`ReactNode`
`asChild`	`boolean`
`heading`	`ReactNode`	Optional heading to render for this group.
`value`	`string`	If no heading is provided, you must provide a value that is unique for this group.
`forceMount`	`boolean`	Whether this group is forcibly rendered regardless of filtering.

<CommandSeparator>

الخاصية	النوع	الافتراضي	الوصف
`asChild`	`boolean`
`alwaysRender`	`boolean`		Whether this separator should always be rendered. Useful if you disable automatic filtering.

<CommandItem>

الخاصية	النوع	الوصف
`value`إلزامي	`string`	Stable value for filtering + the `onSelect` payload. Required: cmdk would otherwise derive it from the rendered text, so a label / translation / icon change would silently change what `onSelect` receives.
`startIcon`	`react.ReactNode`	Leading icon - mirrors Menubar / DropdownMenu item icons.
`shortcut`	`react.ReactNode`	Right-aligned keyboard hint, e.g. `"⌘P"` - mirrors Menubar / DropdownMenu.
`onSelect`	`(value: string) => void`	Fires when the item is chosen (click / Enter). Receives the item's `value` (cmdk defaults it to the text content when `value` is omitted). Action-oriented: items run a command and don't track selection. Inside `CommandDialog` the consumer closes the dialog here, e.g. `onSelect={() => { setOpen(false); run(); }}`.
`children`	`ReactNode`
`asChild`	`boolean`
`disabled`	`boolean`	Whether this item is currently disabled.
`keywords`	`string[]`	Optional keywords to match against when filtering.
`forceMount`	`boolean`	Whether this item is forcibly rendered regardless of filtering.

<CommandDialog>

الخاصية	النوع	الوصف
`open`	`boolean`	Controlled open state.
`defaultOpen`	`boolean`	Initial open state when uncontrolled.
`onOpenChange`	`(open: boolean) => void`
`shortcut`	`string \| false`	Key for the built-in document shortcut (with Cmd on macOS / Ctrl elsewhere). Defaults to `'k'` (⌘K / Ctrl+K). Pass `false` to bind no listener and wire your own. The modifier is fixed; only the key is configurable.
`label`	`react.ReactNode`	Accessible name → visually-hidden `DialogTitle`. Defaults to `"Command palette"`.
`description`	`react.ReactNode`	Optional visually-hidden `DialogDescription`.
`className`	`string`
`children`إلزامي	`react.ReactNode`	`CommandInput` + `CommandList` + groups / items.
`shouldFilter`	`boolean`	Optionally set to `false` to turn off the automatic filtering and sorting. If `false`, you must conditionally render valid items based on the search query yourself.
`filter`	`CommandFilter`	Custom filter function for whether each command menu item should matches the given search query. It should return a number between 0 and 1, with 1 being the best match and 0 being hidden entirely. By default, uses the `command-score` library.
`loop`	`boolean`	Optionally set to `true` to turn on looping around when using the arrow keys.

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

الحقل role="combobox" مرتبط بـ role="listbox" للنتائج، فتتحرّك مفاتيح الأسهم بين المطابقات، ويشغّل Enter العنصر المظلّل، ويغلق Escape. أعطِ الحقل aria-label.

يحصر نمط الحوار التركيز ويعيده عند الإغلاق. الاختصارات المعروضة بجانب العناصر تلميحات؛ وكل عنصر يعمل بالفأرة ولوحة المفاتيح أيضًا.