کامپوننت‌ها
جستجو و انتخاب
فیلد جستجو با فهرست پیشنهادها (Combobox)؛ برای فهرست‌های بلند مثل شهر، کاربر یا محصول.
import { Combobox } from "@kashi-ui/react";وقتی گزینه‌ها بیشتر از ده‌تاست، به‌جای Select از Combobox استفاده کنید. جستجو متن فارسی را یکدست می‌کند: «ي» و «ی»، «ك» و «ک» و ارقام فارسی و انگلیسی یکی حساب می‌شوند.
نمونه
- تهران
- اصفهان
- فارس
- خراسان رضوی
- آذربایجان شرقی
- گیلان
- مازندران
- خوزستان
- کرمان
- یزد
- همدان
- کردستان
«علي» و «علی» یکی حساب می‌شوند.
هنوز انتخابی نشده.
const [city, setCity] = useState<string | null>(null);
<Combobox label="استان" placeholder="جستجو کنید…"
options={provinces.map((p) => ({ value: p, label: p }))}
value={city} onChange={setCity} />گروه، توضیح و آیکون
- طراحی
- سارا محمدیطراح محصول
- رضا کریمیطراح رابط
- فنی
- علی رضاییبرنامهنویس فرانتاند
- مینا احمدیمرخصی
<Combobox label="مسئول" options={[
{ value: "sara", label: "سارا محمدی", description: "طراح محصول", group: "طراحی", icon: <Avatar name="سارا محمدی" size="xs" /> },
{ value: "ali", label: "علی رضایی", group: "فنی", keywords: ["ali"] },
{ value: "mina", label: "مینا احمدی", group: "فنی", disabled: true },
]} />برای جستجوی سمت سرور، onInputChange را بگیرید، options را از پاسخ سرور بسازید، loading را در زمان درخواست روشن کنید و filter={() => true} بدهید.
| نام | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
options | { value, label, description?, icon?, group?, keywords?, disabled? }[] | — | گزینه‌ها؛ گزینه‌های هم‌گروه باید پشت سر هم باشند |
value / defaultValue | string | null | null | مقدار انتخاب‌شده |
onChange | (value: string | null) => void | — | پس از انتخاب یا پاک کردن |
onInputChange | (query: string) => void | — | تغییر متن جستجو |
filter | (option, query) => boolean | defaultFilter | جستجوی سفارشی |
loading | boolean | false | اسپینر و متن «در حال جستجو…» |
emptyMessage | ReactNode | «نتیجه‌ای پیدا نشد.» | متن فهرست خالی |
name | string | — | فیلد پنهان برای ارسال فرم |
label / hint / error | ReactNode | — | مثل ورودی |
ابزارهای defaultFilter، searchText و highlight هم صادر شده‌اند تا در جستجوهای خودتان استفاده کنید.
کیبورد
| کلید | عمل |
|---|---|
| ↓ / ↑ | باز کردن فهرست و رفتن به گزینهٔ بعد / قبل |
| Enter | انتخاب گزینهٔ فعال |
| Esc | بستن فهرست؛ اگر بسته است، پاک کردن مقدار |
| Home / End | اولین / آخرین گزینه (وقتی فهرست باز است) |
دسترس‌پذیری
الگوی Combobox در WAI-ARIA با aria-activedescendant: فوکوس همیشه در فیلد می‌ماند و صفحه‌خوان گزینهٔ فعال را می‌خواند. تعداد نتیجه‌ها پس از هر تایپ با یک ناحیهٔ aria-live اعلام می‌شود («۳ نتیجه») و گزینه‌های غیرفعال aria-disabled دارند.