throttle

گلوگاه‌گذاری: وقتی تابعی پشت سر هم راه می‌افتد، در هر بازه دست‌بالا یک بار اجرا می‌شود. نخستین فراخوانی بی‌درنگ اجرا می‌شود (لبهٔ آغازین) و آخرین فراخوانیِ درون بازه هنگام بسته شدن بازه دوباره اجرا می‌شود (لبهٔ پایانی)، پس وضعیت نهایی هرگز از دست نمی‌رود.

برای پیمایش، جابه‌جایی نشانگر و کشیدن به کارش ببرید؛ هر چیزی که به بازخورد پیوسته نیاز دارد. اگر «تنها مقدار نهایی مهم است» (جست‌وجو هنگام تایپ، ذخیرهٔ خودکار)، از debounce استفاده کنید.

API

throttle(fn, delay?)

پارامترها

پارامتر	توضیح	نوع	پیش‌فرض
fn	تابعی که گلوگاه می‌گیرد	Function	الزامی
delay	کمترین فاصله (میلی‌ثانیه)	number	300

بازگشت

تابعی گلوگاه‌دار که this و آرگومان‌های محل فراخوانی را نگه می‌دارد، به‌علاوهٔ:

عضو	توضیح	نوع
cancel()	فراخوانی پایانیِ در انتظار را دور می‌ریزد	() => void
pending()	اینکه فراخوانی پایانی در انتظار هست یا نه	() => boolean

نمونه

import { throttle } from 'ranuts';

const onScroll = throttle(() => update(window.scrollY), 100);
window.addEventListener('scroll', onScroll);

// هنگام برچیدن — شنونده را بردارید *و* فراخوانی پایانیِ در انتظار را هم دور بریزید
window.removeEventListener('scroll', onScroll);
onScroll.cancel();

یادداشت‌ها

1. لبهٔ آغازین و پایانی: بی‌درنگ اجرا می‌شود و یک بار دیگر در پایان بازه، با تازه‌ترین آرگومان‌ها.
2. this و آرگومان‌ها دست‌نخورده از محل فراخوانی می‌آیند.
3. همه‌جا کار می‌کند: تنها از setTimeout خام بهره می‌برد، پس در Node و Web Worker و SSR هم می‌چرخد.
4. هر فراخوانی throttle() بازهٔ خودش را دارد — دو تابع گلوگاه‌دار هرگز به هم نمی‌زنند.
5. هنگام برچیدن همیشه cancel() را صدا بزنید، وگرنه فراخوانی پایانی در بستری از میان رفته شلیک می‌کند.

در ۰٫۳ برداشته شد

generateThrottle() دیگر نیست. کارخانه‌ای برمی‌گرداند که توابع ساخته‌شده‌اش همگی یک زمان‌سنج و یک برچسب زمانی را با هم شریک بودند، پس دو تابع گلوگاه‌دارِ بی‌ربط، یکدیگر را خفه می‌کردند. const g = generateThrottle(); const f = g(fn, delay) را با throttle(fn, delay) جایگزین کنید.