دیگ

SearchFieldv1.0.0

SearchField روی TextField سوار است و چیزهایی که مخصوص جستجو هستند را اضافه می‌کند: آیکون ذره‌بین، دکمهٔ پاک‌کردن (روشن به‌صورت پیش‌فرض)، Escape برای پاک‌کردن سریع، onSearch برای لحظهٔ Enter، و نشانهٔ کلید میان‌بر (مثل ⌘K) که وقتی فیلد خالی و بی‌فوکوس است دیده می‌شود. خودِ فیلد هیچ منطق فیلتری ندارد: برای نوار جستجو-به‌همراه-فیلتر آن را با Select و Calendar موجود ترکیب کنید (نمونهٔ With Filters پایین).

ری‌اکت ۱۹ و Next.js با پیاده‌سازی دسترس‌پذیری داخلی دیگویو ۳ با Composition API — هنوز برای این کامپوننت پورت نشدهSvelte ۵ با runes — هنوز برای این کامپوننت پورت نشدهانگولار با signals و دایرکتیوهای standalone — هنوز برای این کامپوننت پورت نشده

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

Ctrl+K

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

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

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

نصب

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

پکیج‌منیجر پیش‌فرض Node.jsنصب سریع با لینک سخت و دیسک مشترکYarn نسخهٔ ۲ به بالا (Berry)رانتایم و پکیج‌منیجر Bun
npx digdesign@latest add https://docs.digdesign.ir/r/search-field.json
pnpm dlx digdesign@latest add https://docs.digdesign.ir/r/search-field.json
yarn dlx digdesign@latest add https://docs.digdesign.ir/r/search-field.json
bunx --bun digdesign@latest add https://docs.digdesign.ir/r/search-field.json

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

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

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

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

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

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

استفاده

import { SearchField } from "@/components/ui/search-field"

<SearchField aria-label="جستجو" placeholder="جستجو…" />

// با Enter صدا زده می‌شود؛ onValueChange با هر نویسه اجرا می‌شود
<SearchField
  aria-label="جستجوی محصول"
  onValueChange={setQuery}
  onSearch={(value) => runSearch(value)}
/>

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

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

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

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

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

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

ترکیب اجزا

SearchField دکمهٔ پاک‌کردنِ خودِ Input را با clearable پیش‌فرض روشن نگه می‌دارد و آیکون جستجو را به‌عنوان startContent می‌گذارد؛ یعنی هیچ استایل تازه‌ای نساخته، فقط از سیستم اسلات‌بندیِ موجود Input استفاده کرده است.

پاک‌کردن با Escape هم دقیقاً همان راهی را می‌رود که خودِ دکمهٔ پاک‌کردن Input می‌رود (setNativeValue)، نه یک state جداگانه؛ پس در حالت uncontrolled هم واقعاً مقدار روی صفحه پاک می‌شود، نه فقط رویداد onValueChange شلیک می‌شود.

نشانهٔ کلید میان‌بر با endContent می‌آید و به‌محض تایپ یا فوکوس محو می‌شود، همان الگویی که جعبهٔ جستجوی همین مستندات (بالای سایدبار) استفاده می‌کند.

دسترس‌پذیری

  • وقتی برچسب دیده‌شدنی ندارید (اکثر جعبه‌های جستجوی نوار ابزار)، aria-label بدهید؛ بدون آن صفحه‌خوان فقط «فیلد جستجو» می‌گوید و نمی‌گوید جستجوی چه چیزی.
  • دکمهٔ پاک‌کردن با Tab قابل‌دسترسی نیست (tabIndex={-1}, میراثِ خودِ Input) چون همیشه کنار مقدار قابل‌مشاهده است؛ Escape همان کار را از صفحه‌کلید انجام می‌دهد.
  • نشانهٔ کلید میان‌بر با kbd و dir="ltr" است تا در صفحهٔ راست‌به‌چپ هم به ترتیب درست خوانده شود؛ pointer-events-none دارد پس کلیک رویش وارد فیلد می‌شود.
  • type="search" به صفحه‌خوان می‌گوید این یک فیلد جستجوست، نه یک فیلد متنی عمومی.

مرجع API

SearchField

هر propای که اینجا نیست به TextField و از آنجا به Input می‌رسد: label، description، errorMessage، invalid، size، variant، color، fullWidth و…

ویژگینوعپیش‌فرضتوضیح
onSearch(value: string) => void—با فشردن Enter صدا زده می‌شود؛ برای اجرای واقعی جستجو (fetch)، نه فیلتر زنده.
loadingbooleanfalseآیکون جستجو را با اسپینر عوض می‌کند و دکمهٔ پاک‌کردن را غیرفعال نگه می‌دارد.
shortcutReact.ReactNode—نشانهٔ کلید میان‌بر (مثل «Ctrl+K»)؛ فقط وقتی فیلد خالی و بی‌فوکوس است دیده می‌شود. خودش میان‌بر را ثبت نمی‌کند: فقط نمایش است.
iconReact.ReactNode<SearchIcon />آیکون سفارشی به‌جای ذره‌بین پیش‌فرض.
clearablebooleantrueدکمهٔ پاک‌کردن؛ برخلاف Input که پیش‌فرضش خاموش است، اینجا روشن است.
clearOnEscapebooleantrueکلید Escape مقدار را پاک می‌کند و فوکوس را نگه می‌دارد.
value / defaultValue / onValueChangestring / string / (value: string) => void—هر دو حالت controlled و uncontrolled کار می‌کنند.

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

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

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

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

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

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