دستور (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)
labelstringundefinedبرچسب دسترسی‌پذیر برای منوی دستور (مخفی)
shouldFilterbooleantrueفعال/غیرفعال کردن فیلتر خودکار بر اساس جستجو
filter(value: string, search: string, keywords?: string[]) => numberdefaultFilterتابع فیلتر سفارشی برای تطبیق آیتم‌ها با جستجو
loopbooleanfalseحلقه‌زدن در ناوبری با کلیدهای جهت‌دار
valuestringundefinedمقدار آیتم انتخاب‌شده (کنترل‌شده)
onValueChange(value: string) => voidundefinedفراخوانی هنگام تغییر آیتم انتخاب‌شده

CommandDialog

پراپ‌های CommandDialog (open, onOpenChange).

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
openbooleanundefinedوضعیت باز/بسته بودن دیالوگ
onOpenChange(open: boolean) => voidundefinedفراخوانی هنگام تغییر وضعیت دیالوگ

دسترسی‌پذیری (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>