useDebounce
تأخیر در بهروزرسانی مقدار تا پایان تایپ کاربر
معرفی
هوک useDebounce یک نسخه تأخیری از مقدار ورودی برمیگرداند که فقط بعد از delay میلیثانیه عدم تغییر، بهروزرسانی میشود.
چه زمانی استفاده کنیم
- جستجوی زنده (live search) — جلوگیری از ارسال درخواست با هر کلید
- فیلتر کردن لیستهای بزرگ بر اساس ورودی کاربر
- ذخیره خودکار فرمها بعد از توقف تایپ
چه زمانی استفاده نکنیم
- برای دکمهها و اقدامات یکباره — از throttle یا
disabledstate استفاده کنید - وقتی واکنش فوری لازم است (مثلاً slider)
استفاده
import { useDebounce } from '@parto-system-design/ui'
function SearchComponent() {
const [query, setQuery] = React.useState('')
const debouncedQuery = useDebounce(query, 300)
React.useEffect(() => {
if (debouncedQuery) {
// فقط بعد از 300ms توقف تایپ اجرا میشود
fetchSearchResults(debouncedQuery)
}
}, [debouncedQuery])
return <SearchInput value={query} onChange={(e) => setQuery(e.target.value)} placeholder="جستجو..." />
}الگوی رایج: جستجو با نمایش وضعیت بارگذاری
function LiveSearch() {
const [query, setQuery] = React.useState('')
const [results, setResults] = React.useState([])
const [isLoading, setIsLoading] = React.useState(false)
const debouncedQuery = useDebounce(query, 300)
// نشانگر بارگذاری فوری — بدون debounce
const isTyping = query !== debouncedQuery
React.useEffect(() => {
if (!debouncedQuery) {
setResults([])
return
}
setIsLoading(true)
searchAPI(debouncedQuery)
.then(setResults)
.finally(() => setIsLoading(false))
}, [debouncedQuery])
return (
<div>
<SearchInput value={query} onChange={(e) => setQuery(e.target.value)} />
{(isTyping || isLoading) && <Spinner className="size-4" />}
{results.map((r) => (
<div key={r.id}>{r.title}</div>
))}
</div>
)
}پارامترها
| پارامتر | نوع | توضیح |
|---|---|---|
value | T | مقدار ورودی (هر نوع) |
delay | number | تأخیر بر حسب میلیثانیه |
مقدار بازگشتی
| نوع | توضیح |
|---|---|
T | مقدار debounce شده — همان نوع ورودی |
هوکهای مرتبط
- برای ذخیره مقدار debounce شده در localStorage → useLocalStorage
- برای بارگذاری تدریجی نتایج جستجو → useInfiniteScroll