دیگ

Commandv1.0.0

فهرست دستورهای قابل جستجو با فیلتر زنده و ناوبری کامل با صفحه‌کلید. یا مستقیم داخل صفحه می‌نشیند (مثل جستجوی یک پنل) یا داخل دیالوگ به‌صورت پالت Ctrl+K.

ری‌اکت ۱۹ و Next.js با پیاده‌سازی دسترس‌پذیری داخلی دیگویو ۳ با Composition API — هنوز برای این کامپوننت پورت نشدهSvelte ۵ با runes — هنوز برای این کامپوننت پورت نشدهانگولار با signals و دایرکتیوهای standalone — هنوز برای این کامپوننت پورت نشده

این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.

این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

نصب

با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.

پکیج‌منیجر پیش‌فرض Node.jsنصب سریع با لینک سخت و دیسک مشترکYarn نسخهٔ ۲ به بالا (Berry)رانتایم و پکیج‌منیجر Bun
npx digdesign@latest add https://docs.digdesign.ir/r/command.json
pnpm dlx digdesign@latest add https://docs.digdesign.ir/r/command.json
yarn dlx digdesign@latest add https://docs.digdesign.ir/r/command.json
bunx --bun digdesign@latest add https://docs.digdesign.ir/r/command.json

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

استفاده

import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
} from "@/components/ui/command"

<Command>
  <CommandInput placeholder="جستجو کنید…" />
  <CommandList>
    <CommandEmpty>نتیجه‌ای پیدا نشد.</CommandEmpty>
    <CommandGroup heading="پیشنهادها">
      <CommandItem onSelect={() => router.push("/profile")}>پروفایل</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

ترکیب اجزا

فیلتر کردن را خودِ Command انجام می‌دهد: هرچه در CommandInput تایپ شود، آیتم‌های ناهماهنگ پنهان می‌شوند و گروه‌های خالی هم خودکار حذف می‌شوند.

متن فیلتر از محتوای آیتم خوانده می‌شود؛ اگر آیتم فقط آیکون دارد یا می‌خواهید مترادف‌ها هم پیدا شوند، value را صریح بدهید (مثلاً value="پروفایل حساب کاربری profile").

CommandDialog همین Command را داخل دیالوگ دیگ می‌گذارد و عنوان و توضیحش را برای صفحه‌خوان پنهان نگه می‌دارد.

دسترس‌پذیری

  • ورودی نقش combobox و فهرست نقش listbox دارد؛ آیتم فعال با aria-selected و data-selected مشخص می‌شود.
  • ناوبری با کلیدهای بالا و پایین است و Enter آیتم فعال را انتخاب می‌کند؛ Escape دیالوگ را می‌بندد.
  • CommandEmpty را همیشه بگذارید تا وقتی نتیجه‌ای نیست، کاربر صفحه‌خوان هم بفهمد جستجو خالی است.
  • میان‌بر Ctrl+K را خودتان با شنوندهٔ keydown وصل کنید و آن را در رابط نشان دهید تا کشف‌شدنی باشد.
  • CommandShortcut فقط نمایشی است و با dir=ltr رندر می‌شود تا ترتیب کلیدها در متن فارسی به‌هم نریزد.

مرجع API

Command

ویژگینوعپیش‌فرضتوضیح
value / onValueChangestring / (value: string) => void—کنترل آیتمی که هم‌اکنون فعال است.
shouldFilterbooleantrueخاموش کردن فیلتر داخلی وقتی نتیجه‌ها را خودتان از سرور می‌گیرید.
loopbooleanfalseبرگشت از آخرین آیتم به اولی با کلید جهت‌دار.

CommandDialog

ویژگینوعپیش‌فرضتوضیح
open / onOpenChangeboolean / (open: boolean) => void—باز و بسته بودن دیالوگ.
titlestring"پالت دستورها"عنوان پنهان برای صفحه‌خوان.
descriptionstring—توضیح پنهان برای صفحه‌خوان.
showCloseButtonbooleantrueنمایش دکمهٔ بستن دیالوگ.

CommandItem / CommandGroup

ویژگینوعپیش‌فرضتوضیح
CommandItem valuestring—متنی که فیلتر روی آن اجرا می‌شود؛ برای مترادف‌ها صریح بدهید.
CommandItem onSelect(value: string) => void—هنگام انتخاب با کلیک یا Enter صدا زده می‌شود.
CommandItem disabledbooleanfalseآیتم دیده می‌شود ولی انتخاب نمی‌شود.
CommandGroup headingReact.ReactNode—عنوان دسته؛ اگر همهٔ آیتم‌های گروه فیلتر شوند، خودکار پنهان می‌شود.

CommandInput / CommandList / CommandEmpty

ویژگینوعپیش‌فرضتوضیح
CommandInput value / onValueChangestring / (value: string) => void—کنترل متن جستجو، مثلاً برای جستجوی سمت سرور.
CommandListComponent—ناحیهٔ اسکرول نتایج؛ ارتفاع بیشینه‌اش پیش‌فرض ۳۰۰ پیکسل است.
CommandEmptyComponent—فقط وقتی هیچ نتیجه‌ای نیست رندر می‌شود.

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.