このページはまだ翻訳されていないため、英語で表示されます。 翻訳に参加する

fxDebounce

Delays a function call until wait has passed since the last call — only the trailing call in a burst survives.

Debounced<T> fxDebounce<T>(void Function(T arg) func, Duration wait, {bool leading = false, Duration? maxWait}) class Debounced<T> { void call(T arg); // Debounced is callable: debounced(arg) void cancel(); void flush(); // run the pending call now bool get isPending; } FxEvents<T> FxEvents<T>.debounce(Duration window) // chain (events) Debounced<T> (void Function(T arg)).fxDebounce(Duration wait, {bool leading = false, Duration? maxWait}) // method

Lecture

fxDebounce wraps a callback so that repeated calls in quick succession collapse into a single call. Every call restarts a timer of length wait; the wrapped func only actually fires once wait has passed without another call — and it fires with whatever argument was passed in that last call. This is the classic "wait for the user to stop typing before searching" pattern.

In JS, FxTS attaches a .cancel() method directly onto the returned function. Dart functions can't carry extra members, so FxDart returns a Debounced<T> instead — a class with a call(T arg) method, which Dart lets you invoke with plain function-call syntax (debounced(arg)) thanks to the call() convention, plus an explicit .cancel() to drop any pending invocation.

By default (leading: false), only the trailing edge fires — the last call in a burst, after things go quiet. Pass leading: true and the first call in a burst fires immediately instead, with every call before the next quiet period suppressed.

Two things a debounce in a real app needs on top of that. maxWait caps how long calls can keep postponing the run: a slider dragged without a pause would otherwise never save at all, while with maxWait: 2s it saves the newest value at least every two seconds. And .flush() runs the pending call now — what an app-pause or dispose hook wants, since .cancel() would lose the last value and the timer may never get to fire. .isPending says whether there is anything to flush. These three are fxdart additions (after lodash); FxTS's debounce has only cancel.

Demo 1 · Trailing edge (the default)

Three rapid calls collapse into one — only the last argument survives:

Demo 2 · Leading edge and cancel()

leading: true fires immediately and suppresses the rest of the burst; .cancel() drops a pending trailing call entirely:

Demo 3 · maxWait and flush()

A drag that never pauses still saves on the maxWait schedule, and flush() writes the last value before the app goes away:

Method spelling

The callback carries the same thing as a method: saveDraft.fxDebounce(wait) is fxDebounce(saveDraft, wait), named arguments and all.

void saveDraft(String text) => _post(text);

final save = saveDraft.fxDebounce(const Duration(milliseconds: 300));
save('h');
save('he');
save('hello');   // only this one reaches _post

The fx prefix is deliberate. It says which library is wrapping the callback and leaves the bare name free for whatever else a project puts on its function types — the same convention as the getter spellings in fx.

Try it yourself

Exercise: wrap save in fxDebounce (100ms wait) so only the final value survives the burst of calls below.

On event streams

The same idea exists on the events layer: when the bursty thing is a Stream rather than a callback, fxEvents(s).debounce(window) emits the trailing value of each burst once window has passed without a newer event — and a value still pending when the stream closes is flushed, never dropped. See fxEvents for the chain this belongs to.

Related: fxThrottle — fires on a schedule instead of after quiet · fxOnChange — skip calls whose value did not change · fxConflate — one async run at a time, newest value next · fxDelay & fxSleep — building timing demos · concurrent — rate-limiting for async pipelines · fxShuffle — seeded randomness