جستجو با پیشنهاد
جعبهٔ جستجو با جستجوهای اخیر و پرطرفدار و پیشنهاد هنگام تایپ؛ الگوی جستجوی فروشگاههای اینترنتی.
npm i @kashi-ui/react @kashi-ui/cssimport { SearchSuggest } from "@kashi-ui/react";CSS را یک بار در ریشهٔ برنامه وارد کنید: import "@kashi-ui/css"حجم: ۲٫۲ کیلوبایت + هستهٔ مشترکراهنمای نصب
npx shadcn@latest add @kashi/search-suggestکد خودِ کامپوننت در پوشهٔ components/kashi پروژهٔ شما کپی میشود. برای نسخههای قدیمی shadcn، راهنمای «دربارهٔ shadcn» را ببینید.دربارهٔ shadcn
npm i @kashi-ui/elements @kashi-ui/cssimport "@kashi-ui/elements/commerce.js";<kashi-search-suggest></kashi-search-suggest>بدون React، برای HTML، وردپرس، Vue و Angular.CDN، نمونه و ویژگیها
import { SearchSuggest } from "@kashi-ui/react";
نمونه
روی فیلد بزنید: با فیلد خالی، جستجوهای اخیر (با «پاک کردن») و جستجوهای پرطرفدار با آیکون روند دیده میشوند. با تایپ، پیشنهادها با قسمت پیداشدهٔ پررنگ میآیند.
روی فیلد بزنید
<SearchSuggest
placeholder="جستجو در همهٔ کالاها"
recent={recent}
onClearRecent={() => setRecent([])}
popular={["ساعت مچی زنانه", "عروسک", "اسکوتر برقی"]}
suggestions={products}
onSearch={(q) => router.push(`/search?q=${q}`)}
/>ذخیرهٔ خودکار جستجوهای اخیر
اگر جستجوهای اخیر را خودتان نگه نمیدارید، storageKey بدهید. هر جستجو (حداکثر ۸ مورد) در مرورگر کاربر ذخیره میشود و «پاک کردن» همه را حذف میکند.
<SearchSuggest storageKey="shop-recent" popular={popular} onSearch={search} />
پیشنهاد از سرور
بهجای آرایه، تابعی بدهید که برای هر عبارت فهرست برگرداند؛ مثلاً از نتیجهٔ آخرین درخواست. جستجوی آرایهای «ی» و «ک» عربی و نیمفاصله را یکسان میبیند.
<SearchSuggest suggestions={(q) => results[q] ?? []} onChange={fetchSuggestions} />
| نام | توضیح، نوع و پیشفرض |
|---|---|
value / defaultValue | متن جستجو |
onChange | با هر تایپ |
onSearch | با Enter یا انتخاب پیشنهاد، جستجوی اخیر یا پرطرفدار |
recent | جستجوهای اخیر (کنترلشده) |
onClearRecent | دکمهٔ «پاک کردن» |
storageKey | ذخیرهٔ خودکار جستجوهای اخیر در localStorage |
popular | جستجوهای پرطرفدار |
suggestions | پیشنهادها هنگام تایپ (حداکثر ۸) |
placeholder / label / name | label برای صفحهخوان؛ پیشفرض «جستجو» |
دسترسپذیری
فیلد نقش combobox دارد و پیشنهادها listbox هستند؛ با ↓ و ↑ بین پیشنهادها جابهجا میشوید، Enter جستجو میکند و Escape پنل را میبندد (و بار دوم متن را پاک میکند). جستجوهای اخیر و پرطرفدار دکمهاند و با Tab در دسترساند. فرم نقش search دارد تا صفحهخوان آن را بهعنوان بخش جستجو بشناسد.
راهنمای استفاده
کِی استفاده کنیم
- جستجوی اصلی فروشگاه یا سایت محتوایی که کاربر معمولاً دوباره همان چیزها را جستجو میکند.
- جایی که جستجوهای پرطرفدار به کشف محصول کمک میکند.
کِی استفاده نکنیم
- انتخاب یک مقدار از فهرست ثابت در فرم. کامبوباکس
- جستجوی دستورها و صفحههای داخل پنل مدیریت. کامند پالت
- فیلتر سریع یک جدول کوچک؛ یک فیلد ساده کافی است. ورودی
درست و نادرست
- درست
درست: حداکثر ۵ تا ۸ جستجوی پرطرفدار واقعی، بهروز با آمار جستجو. نادرستنادرست: فهرست بلندی از کلمهها که برای سئو یا تبلیغ پر شده. - درست
درست: دکمهٔ «پاک کردن» برای جستجوهای اخیر؛ کاربر باید بتواند تاریخچهاش را حذف کند. نادرستنادرست: تاریخچهای که همیشه میماند، حتی روی دستگاه مشترک.
متن
- placeholder بگوید کجا جستجو میشود: «جستجو در همهٔ کالاها»، نه فقط «جستجو».
- عنوان بخشها کوتاه: «جستجوهای اخیر» و «جستجوهای پرطرفدار».
قاعدههای کلی لحن، برچسب دکمه و پیام خطا: نوشتن متن رابط
وب کامپوننت
همین کامپوننت بدون React، برای HTML، وردپرس، Vue، Svelte و Angular: <kashi-search-suggest> در @kashi-ui/elements. فهرستها با ویرگول (, یا ،) جدا میشوند. با storage-key جستجوهای اخیر در مرورگر ذخیره میشوند؛ با action فرم به همان نشانی و با پارامتر q ارسال میشود.
نصب
بدون ابزار ساخت، این دو خط را در <head> صفحه بگذارید:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kashi-ui/css/dist/kashi.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@kashi-ui/elements/dist/cdn/kashi-elements.js"></script>یا با npm، و فقط همین بخش را وارد کنید:
npm i @kashi-ui/elements @kashi-ui/cssimport "@kashi-ui/css";
import "@kashi-ui/elements/commerce.js";نمونه
<kashi-search-suggest
placeholder="جستجو در همهٔ کالاها"
popular="ساعت هوشمند، عروسک، اسکوتر برقی"
suggestions="ساعت مچی زنانه، ساعت هوشمند، گوشی هوشمند، هدفون بیسیم، میز آرایش"
storage-key="demo-recent"
></kashi-search-suggest>ویژگیها
| نام | توضیح، نوع و پیشفرض |
|---|---|
placeholder | متن راهنمای فیلد |
popular | جستجوهای پرطرفدار |
suggestions | پیشنهادها هنگام تایپ |
recent | جستجوهای اخیر (اگر storage-key ندارید) |
storage-key | ذخیرهٔ خودکار جستجوهای اخیر در localStorage |
action | ارسال فرم جستجو به این نشانی |
name | نام فیلد در فرم |
رویدادها و JavaScript
| نام | توضیح |
|---|---|
kashi-search | detail: { query } |
kashi-change | detail: { value } |
.value | متن فعلی |