پالت دستورات (Command)

معرفی

کامپوننت Command یک پالت دستورات قدرتمند برای جستجو و اجرای دستورات است. معمولا با کلید ترکیبی Cmd+K یا Ctrl+K فعال می‌شود.

چه زمانی استفاده کنیم:

• وقتی نیاز به پالت دستورات سراسری با جستجوی فازی دارید
• برای ناوبری سریع بین بخش‌های مختلف اپلیکیشن
• وقتی کاربران حرفه‌ای نیاز به کلید میانبر برای اجرای اقدامات دارند

چه زمانی استفاده نکنیم:

• برای فرم‌های ساده — از Select یا Autocomplete استفاده کنید
• وقتی کاربر باید فقط تایپ کند بدون انتخاب از لیست — از Input استفاده کنید
• برای انتخاب‌های ساده با لیست کوچک — از Select استفاده کنید

زمین بازی

با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.

استفاده

import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
} from '@partodata/ui'

export default function MyComponent() {
  return (
    <Command>
      <CommandInput placeholder="جستجو کنید..." />
      <CommandList>
        <CommandEmpty>نتیجه‌ای یافت نشد.</CommandEmpty>
        <CommandGroup heading="پیشنهادات">
          <CommandItem>تقویم</CommandItem>
          <CommandItem>نشانه‌ها</CommandItem>
          <CommandItem>تنظیمات</CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  )
}

به صورت Dialog

import { CommandDialog } from '@partodata/ui'
import { useEffect, useState } from 'react'

export default function MyComponent() {
  const [open, setOpen] = useState(false)

  useEffect(() => {
    const down = (e: KeyboardEvent) => {
      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
        e.preventDefault()
        setOpen((open) => !open)
      }
    }
    document.addEventListener('keydown', down)
    return () => document.removeEventListener('keydown', down)
  }, [])

  return (
    <CommandDialog open={open} onOpenChange={setOpen}>
      <CommandInput placeholder="جستجو کنید..." />
      <CommandList>
        <CommandEmpty>نتیجه‌ای یافت نشد.</CommandEmpty>
        <CommandGroup heading="پیشنهادات">
          <CommandItem>تقویم</CommandItem>
          <CommandItem>نشانه‌ها</CommandItem>
        </CommandGroup>
      </CommandList>
    </CommandDialog>
  )
}

با Separator

<Command>
  <CommandInput />
  <CommandList>
    <CommandGroup heading="گروه اول">
      <CommandItem>آیتم 1</CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="گروه دوم">
      <CommandItem>آیتم 2</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

با کلید میانبر

<CommandItem>
  <span>تنظیمات</span>
  <CommandShortcut>⌘S</CommandShortcut>
</CommandItem>

ترکیب کامپوننت‌ها

• Command: کانتینر اصلی با قابلیت جستجوی فازی
• CommandDialog: Command در داخل Dialog (برای پالت دستورات)
• CommandInput: فیلد جستجو
• CommandList: لیست نتایج (با scroll خودکار)
• CommandEmpty: محتوای نمایش وقتی نتیجه‌ای نیست
• CommandGroup: گروه‌بندی آیتم‌ها با عنوان
• CommandItem: هر دستور یا گزینه
• CommandSeparator: خط جداکننده بین گروه‌ها
• CommandShortcut: نمایش کلید میانبر در کنار آیتم

Props

CommandDialog

علاوه بر این، CommandDialog تمام props کامپوننت Dialog را نیز می‌پذیرد.

CommandInput

CommandGroup

CommandItem

حالت‌ها و انواع

حالت Inline

Command به صورت مستقیم در صفحه نمایش داده می‌شود (بدون Dialog).

حالت Dialog

با CommandDialog در داخل یک Dialog modal نمایش داده می‌شود و معمولاً با Cmd+K فعال می‌شود.

با گروه‌بندی

آیتم‌ها را با CommandGroup و heading گروه‌بندی کنید.

با کلید میانبر

از CommandShortcut برای نمایش کلید میانبر در کنار هر آیتم استفاده کنید.

راهنمای استفاده

دسترسی‌پذیری

• پیمایش بین آیتم‌ها با ↑ و ↓
• انتخاب آیتم با Enter
• بستن CommandDialog با Escape
• جستجوی فازی (Fuzzy search) خودکار بر اساس متن آیتم‌ها
• نقش combobox برای فیلد جستجو و listbox برای لیست نتایج
• پشتیبانی کامل از RTL

کامپوننت‌های مرتبط

• اگر نیاز به انتخاب ساده با جستجو و پیشنهادات دارید → Autocomplete
• اگر نیاز به انتخاب چندین گزینه از لیست دارید → MultiSelect
• اگر فقط نیاز به یک فیلد جستجوی ساده دارید → SearchInput