دستور (Command)
منوی دستور برای جستجو و اقدامات سریع. بر پایه کتابخانه cmdk ساخته شده است.
نصب (Installation)
1npx @quark-lab/rad-ui add commandنمونهها (Examples)
استفاده پایه (Basic)
منوی دستور ساده با گروهها و جداکننده
نتیجهای یافت نشد.
تقویم
جستجوی ایموجی
ماشینحساب
پروفایل
صورتحساب
تنظیمات
مشاهده کد
1import {
2 Command,
3 CommandEmpty,
4 CommandGroup,
5 CommandInput,
6 CommandItem,
7 CommandList,
8 CommandSeparator,
9} from "@/components/ui/command";
10
11export default function BasicExample() {
12 return (
13 <Command className="max-w-sm rounded-lg border">
14 <CommandInput placeholder="جستجو یا تایپ دستور..." />
15 <CommandList>
16 <CommandEmpty>نتیجهای یافت نشد.</CommandEmpty>
17 <CommandGroup heading="پیشنهادات">
18 <CommandItem>تقویم</CommandItem>
19 <CommandItem>جستجوی ایموجی</CommandItem>
20 <CommandItem>ماشینحساب</CommandItem>
21 </CommandGroup>
22 <CommandSeparator />
23 <CommandGroup heading="تنظیمات">
24 <CommandItem>پروفایل</CommandItem>
25 <CommandItem>صورتحساب</CommandItem>
26 <CommandItem>تنظیمات</CommandItem>
27 </CommandGroup>
28 </CommandList>
29 </Command>
30 );
31}
32پالت دستور (Command Palette) (Command Palette)
منوی دستور در دیالوگ با میانبر ⌘K و نمایش کلیدهای میانبر
مشاهده کد
1"use client";
2
3import { useState, useEffect } from "react";
4import {
5 Command,
6 CommandDialog,
7 CommandEmpty,
8 CommandGroup,
9 CommandInput,
10 CommandItem,
11 CommandList,
12 CommandSeparator,
13 CommandShortcut,
14 Button,
15} from "@/components/ui/command";
16
17export default function DialogExample() {
18 const [open, setOpen] = useState(false);
19
20 useEffect(() => {
21 const down = (e: KeyboardEvent) => {
22 if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
23 e.preventDefault();
24 setOpen((o) => !o);
25 }
26 };
27 document.addEventListener("keydown", down);
28 return () => document.removeEventListener("keydown", down);
29 }, []);
30
31 return (
32 <>
33 <Button variant="outline" onClick={() => setOpen(true)}>
34 باز کردن منو (⌘K)
35 </Button>
36 <CommandDialog open={open} onOpenChange={setOpen}>
37 <CommandInput placeholder="جستجو برای دستور..." />
38 <CommandList>
39 <CommandEmpty>نتیجهای یافت نشد.</CommandEmpty>
40 <CommandGroup heading="پیشنهادات">
41 <CommandItem>
42 تقویم
43 <CommandShortcut>⌘P</CommandShortcut>
44 </CommandItem>
45 <CommandItem>
46 صورتحساب
47 <CommandShortcut>⌘B</CommandShortcut>
48 </CommandItem>
49 <CommandItem>
50 تنظیمات
51 <CommandShortcut>⌘S</CommandShortcut>
52 </CommandItem>
53 </CommandGroup>
54 <CommandSeparator />
55 <CommandGroup heading="تنظیمات">
56 <CommandItem>پروفایل</CommandItem>
57 <CommandItem>صورتحساب</CommandItem>
58 <CommandItem>تنظیمات</CommandItem>
59 </CommandGroup>
60 </CommandList>
61 </CommandDialog>
62 </>
63 );
64}
65مرجع API (API Reference)
Command
پراپهای کامپوننت Command.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
label | string | undefined | برچسب دسترسیپذیر برای منوی دستور (مخفی) |
shouldFilter | boolean | true | فعال/غیرفعال کردن فیلتر خودکار بر اساس جستجو |
filter | (value: string, search: string, keywords?: string[]) => number | defaultFilter | تابع فیلتر سفارشی برای تطبیق آیتمها با جستجو |
loop | boolean | false | حلقهزدن در ناوبری با کلیدهای جهتدار |
value | string | undefined | مقدار آیتم انتخابشده (کنترلشده) |
onValueChange | (value: string) => void | undefined | فراخوانی هنگام تغییر آیتم انتخابشده |
CommandDialog
پراپهای CommandDialog (open, onOpenChange).
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
open | boolean | undefined | وضعیت باز/بسته بودن دیالوگ |
onOpenChange | (open: boolean) => void | undefined | فراخوانی هنگام تغییر وضعیت دیالوگ |
دسترسیپذیری (Accessibility)
کیبورد (Keyboard)
ArrowDown/Ctrl+N- حرکت به آیتم بعدیArrowUp/Ctrl+P- حرکت به آیتم قبلیEnter- انتخاب آیتمEscape- بستن (در CommandDialog)
نقشهای ARIA
از role="combobox" برای ورودی و role="listbox" برای لیست استفاده میشود
بهترین شیوهها (Best Practices)
گروهبندی (Grouping)
از CommandGroup و CommandSeparator برای سازماندهی دستورات استفاده کنید
مقدار آیتم (Item Value)
برای آیتمهای پویا حتماً prop value را تنظیم کنید تا جستجو درست کار کند
میانبر صفحهکلید
برای Command Palette از ⌘K یا Ctrl+K استفاده کنید و با useEffect آن را پیادهسازی کنید
نحوه استفاده (Usage)
1import {
2 Command,
3 CommandDialog,
4 CommandEmpty,
5 CommandGroup,
6 CommandInput,
7 CommandItem,
8 CommandList,
9 CommandSeparator,
10 CommandShortcut,
11} from "@/components/ui/command";
12
13// استفاده inline
14<Command className="max-w-sm rounded-lg border">
15 <CommandInput placeholder="جستجو..." />
16 <CommandList>
17 <CommandEmpty>نتیجهای یافت نشد.</CommandEmpty>
18 <CommandGroup heading="گروه ۱">
19 <CommandItem value="item-1">آیتم ۱</CommandItem>
20 <CommandItem value="item-2">آیتم ۲</CommandItem>
21 </CommandGroup>
22 <CommandSeparator />
23 <CommandGroup heading="گروه ۲">
24 <CommandItem value="item-3" onSelect={() => console.log("selected")}>
25 آیتم ۳
26 <CommandShortcut>⌘K</CommandShortcut>
27 </CommandItem>
28 </CommandGroup>
29 </CommandList>
30</Command>
31
32// استفاده به صورت Command Palette (دیالوگ)
33const [open, setOpen] = useState(false);
34
35<CommandDialog open={open} onOpenChange={setOpen}>
36 <CommandInput placeholder="جستجو برای دستور..." />
37 <CommandList>
38 <CommandEmpty>نتیجهای یافت نشد.</CommandEmpty>
39 <CommandGroup heading="دستورات">
40 <CommandItem onSelect={() => setOpen(false)}>بستن</CommandItem>
41 </CommandGroup>
42 </CommandList>
43</CommandDialog>