پالت دستورات (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
CommandInput
CommandGroup
CommandItem
حالتها و انواع
حالت 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