ددیگ

Command

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

ری‌اکت ۱۹ و Next.js با پیاده‌سازی دسترس‌پذیری داخلی دیگویو ۳ با Composition API و Reka UISvelte ۵ با runes و Bits UIانگولار با signals و Angular CDK

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

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

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

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

نصب

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

نصب سریع با لینک سخت و دیسک مشترکپکیج‌منیجر پیش‌فرض Node.jsYarn نسخهٔ ۲ به بالا (Berry)رانتایم و پکیج‌منیجر Bun
pnpm dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/command.json
npx dig-ui@latest add https://design-system-tau-green.vercel.app/r/command.json
yarn dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/command.json
bunx --bun dig-ui@latest add https://design-system-tau-green.vercel.app/r/command.json

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

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

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

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

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

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

استفاده

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 پورت نشده است.

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

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

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

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

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

ترکیب اجزا

فیلتر کردن را خودِ 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 پورت نشده است.

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

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

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

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

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