پرتوپرتو

useDebounce

تأخیر در به‌روزرسانی مقدار تا پایان تایپ کاربر

معرفی

هوک useDebounce یک نسخه تأخیری از مقدار ورودی برمی‌گرداند که فقط بعد از delay میلی‌ثانیه عدم تغییر، به‌روزرسانی می‌شود.

چه زمانی استفاده کنیم

  • جستجوی زنده (live search) — جلوگیری از ارسال درخواست با هر کلید
  • فیلتر کردن لیست‌های بزرگ بر اساس ورودی کاربر
  • ذخیره خودکار فرم‌ها بعد از توقف تایپ

چه زمانی استفاده نکنیم

  • برای دکمه‌ها و اقدامات یک‌باره — از throttle یا disabled state استفاده کنید
  • وقتی واکنش فوری لازم است (مثلاً 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>
  )
}

پارامترها

پارامترنوعتوضیح
valueTمقدار ورودی (هر نوع)
delaynumberتأخیر بر حسب میلی‌ثانیه

مقدار بازگشتی

نوعتوضیح
Tمقدار debounce شده — همان نوع ورودی

هوک‌های مرتبط

  • برای ذخیره مقدار debounce شده در localStorage → useLocalStorage
  • برای بارگذاری تدریجی نتایج جستجو → useInfiniteScroll