Window.cancelIdleCallback() — Methode · JavaScript-Referenz

Signatur

Window.cancelIdleCallback(handle)

Beschreibung

window.cancelIdleCallback() ist das Gegenstück zu window.requestIdleCallback(). Beim Planen gibt requestIdleCallback() eine ganzzahlige ID zurück. Übergibst du diese ID an cancelIdleCallback(), entfernt der Browser den Callback aus seiner Warteschlange. Er wird dann nicht mehr aufgerufen, auch nicht, wenn ein gesetztes timeout abläuft.

Gebraucht wird die Methode vor allem, wenn geplante Hintergrundarbeit überflüssig wird, bevor der Browser Leerlaufzeit dafür findet. Typische Fälle:

Eine Komponente wird entfernt (Unmount), bevor ihre aufgeschobene Arbeit gelaufen ist.
Neue Nutzereingaben machen eine geplante Vorberechnung wertlos, etwa beim Entprellen (Debouncing) von Such-Vorschlägen.
Analytics- oder Protokolldaten wurden inzwischen auf anderem Weg gesendet, z. B. über navigator.sendBeacon() beim Verlassen der Seite.

Der Aufruf ist gefahrlos. Ist die ID ungültig, schon abgearbeitet oder schon abgebrochen, passiert einfach nichts. Es wird kein Fehler geworfen.

Parameter

Name	Typ	Default	Beschreibung
$handle Pflicht	number		Die ID, die `window.requestIdleCallback()` beim Planen zurückgegeben hat.

Rückgabewert

Typ

void

Beschreibung

Gibt nichts zurück (undefined).

Beispiele

Geplanten Idle-Callback wieder abbrechen

const id = requestIdleCallback((deadline) => {
  console.log('Wird nie ausgegeben');
});

// Die Arbeit wird doch nicht gebraucht
cancelIdleCallback(id);
console.log(`Callback ${id} abgebrochen`);

Callback 1 abgebrochen

Vorberechnung bei neuer Eingabe verwerfen (Debouncing)

const input = document.querySelector('#suche');
let idleId = null;

const berechneVorschlaege = (begriff) => {
  console.log(`Berechne Vorschläge für "${begriff}"`);
};

input.addEventListener('input', (event) => {
  // Veraltete Vorberechnung abbrechen
  if (idleId !== null) {
    cancelIdleCallback(idleId);
  }
  const begriff = event.target.value;
  idleId = requestIdleCallback(() => {
    idleId = null;
    berechneVorschlaege(begriff);
  }, { timeout: 500 });
});

Berechne Vorschläge für "java"

Aufräumen beim Entfernen einer Komponente

class LazyWidget {
  #idleId = null;

  mount(container) {
    this.container = container;
    this.#idleId = requestIdleCallback((deadline) => {
      this.#idleId = null;
      console.log(`Rendere, verbleibend: ${deadline.timeRemaining().toFixed(1)} ms`);
      this.container.textContent = 'Widget geladen';
    });
  }

  unmount() {
    if (this.#idleId !== null) {
      cancelIdleCallback(this.#idleId);
      this.#idleId = null;
      console.log('Ausstehende Idle-Arbeit verworfen');
    }
  }
}

const widget = new LazyWidget();
widget.mount(document.body);
widget.unmount();

Ausstehende Idle-Arbeit verworfen

Fallback für Browser ohne Unterstützung

const ric = window.requestIdleCallback ??
  ((cb) => setTimeout(() => cb({ didTimeout: false, timeRemaining: () => 0 }), 1));
const cic = window.cancelIdleCallback ?? ((id) => clearTimeout(id));

const id = ric(() => console.log('läuft nicht'));
cic(id);
console.log('Abgebrochen – auch in Safari');

Abgebrochen – auch in Safari

// Wichtig · Fallstricke

Browserunterstützung: Chromium-Browser und Firefox unterstützen die Methode. Safari bietet requestIdleCallback() und cancelIdleCallback() bislang nicht standardmäßig an. Prüfe deshalb vorher, ob die API vorhanden ist, oder weiche auf setTimeout()/clearTimeout() aus.

Fallstricke:

Nur IDs aus requestIdleCallback() verwenden. IDs aus setTimeout() oder requestAnimationFrame() gehören zu anderen Warteschlangen. Mit ihnen bricht die Methode nichts ab. Die Ausnahme ist ein Fallback, der auch beim Planen setTimeout() nutzt.
Ein Callback, der bereits läuft oder fertig ist, lässt sich nicht mehr stoppen. Setze die gespeicherte ID am Anfang des Callbacks auf null, damit dein Zustand stimmt.
Auch ein gesetztes timeout wird mit abgebrochen. Der Callback läuft dann garantiert nicht.
Die Methode gibt es nur im Fensterkontext (Window), nicht in Web Workers.

Siehe auch

Window.requestIdleCallback() IdleDeadline Window.cancelAnimationFrame() Scheduler.postTask() new VTTCue() Window.createImageBitmap()