پرتوپرتو

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

یک کامپوننت جستجو و پالت دستورات سریع

معرفی

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

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

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

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

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

استفاده

import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
} from '@parto-system-design/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 '@parto-system-design/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

Prop

Type

CommandInput

Prop

Type

CommandGroup

Prop

Type

CommandItem

Prop

Type

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

حالت Inline

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

حالت Dialog

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

با گروه‌بندی

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

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

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

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

بکنید

  • آیتم‌ها را با CommandGroup گروه‌بندی کنید تا ساختار واضحی داشته باشند - CommandEmpty را تعریف کنید تا کاربر بداند جستجو نتیجه‌ای نداشته است - از CommandShortcut برای نمایش کلیدهای میانبر استفاده کنید

نکنید

  • از Command به‌عنوان جایگزین Select در فرم‌ها استفاده نکنید — Command برای اقدامات سریع است - آیتم‌های زیادی بدون گروه‌بندی قرار ندهید - بدون CommandEmpty رها نکنید — کاربر باید بازخورد دریافت کند

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

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

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

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