DedicatedWorkerGlobalScope.cancelAnimationFrame() — Methode · JavaScript-Referenz

Signatur

DedicatedWorkerGlobalScope.cancelAnimationFrame(handle)

Beschreibung

Die Methode cancelAnimationFrame() des DedicatedWorkerGlobalScope ist das Gegenstück zu requestAnimationFrame() innerhalb eines Dedicated Workers. Sie nimmt die Kennung (Handle) entgegen, die requestAnimationFrame() zurückgegeben hat, und entfernt den zugehörigen Callback aus der Liste der Animationsframe-Callbacks, bevor er beim nächsten Frame ausgeführt wird.

Richtig nützlich wird das zusammen mit OffscreenCanvas: Der Hauptthread überträgt ein Canvas per transferControlToOffscreen() an einen Worker, der dort seine eigene Render-Schleife mit requestAnimationFrame() betreibt. Mit cancelAnimationFrame() lässt sich diese Schleife dann sauber anhalten, etwa wenn der Hauptthread eine „Pause“- oder „Stopp“-Nachricht schickt oder die Szene nicht mehr sichtbar ist.

Die Methode steht nur in Dedicated Workers zur Verfügung, nicht in Shared Workers oder Service Workers. Ist die übergebene Kennung ungültig oder wurde der Callback schon ausgeführt, passiert einfach nichts. Es wird kein Fehler ausgelöst.

Parameter

Name	Typ	Default	Beschreibung
$handle Pflicht	number		Die von `requestAnimationFrame()` zurückgegebene ganzzahlige Kennung der Anforderung, die abgebrochen werden soll.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Render-Schleife im Worker starten und stoppen

// worker.js
let canvas = null;
let ctx = null;
let frameId = null;
let x = 0;

const render = (time) => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.fillRect(x, 50, 40, 40);
  x = (x + 2) % canvas.width;
  frameId = self.requestAnimationFrame(render);
};

self.onmessage = ({ data }) => {
  switch (data.type) {
    case 'init':
      canvas = data.canvas;
      ctx = canvas.getContext('2d');
      break;
    case 'start':
      if (frameId === null) frameId = self.requestAnimationFrame(render);
      break;
    case 'stop':
      if (frameId !== null) {
        self.cancelAnimationFrame(frameId);
        frameId = null;
        console.log('Animation gestoppt');
      }
      break;
  }
};

Animation gestoppt

Hauptthread: OffscreenCanvas übergeben und steuern

// main.js
const canvas = document.querySelector('canvas');
const offscreen = canvas.transferControlToOffscreen();
const worker = new Worker('worker.js');

worker.postMessage({ type: 'init', canvas: offscreen }, [offscreen]);
worker.postMessage({ type: 'start' });

// Bei verstecktem Tab die Schleife im Worker anhalten
document.addEventListener('visibilitychange', () => {
  worker.postMessage({ type: document.hidden ? 'stop' : 'start' });
});

Einzelne geplante Anforderung sofort verwerfen

// worker.js
const id = self.requestAnimationFrame(() => {
  console.log('Wird nie ausgegeben');
});

self.cancelAnimationFrame(id);
console.log(`Anforderung ${id} abgebrochen`);

Anforderung 1 abgebrochen

// Wichtig · Fallstricke

Nur in Dedicated Workers: In SharedWorkerGlobalScope und ServiceWorkerGlobalScope gibt es die Methode nicht. Mit typeof self.cancelAnimationFrame === 'function' lässt sich das vorher prüfen.
Aktuelle Kennung speichern: In einer rekursiven Schleife liefert jeder Aufruf von requestAnimationFrame() eine neue Kennung. Merkst du dir nur die erste, bricht cancelAnimationFrame() die laufende Schleife nicht ab.
Ungültige oder bereits verbrauchte Kennungen werden stillschweigend ignoriert. Tippfehler oder veraltete IDs fallen deshalb nicht durch Fehlermeldungen auf.
Kennungen gelten nur im jeweiligen Kontext. Eine ID aus dem Hauptthread (window.requestAnimationFrame) lässt sich nicht im Worker abbrechen, und umgekehrt geht es auch nicht.
Browser-Unterstützung: Chrome/Edge 69+, Firefox 97+, Safari 16.4+. Ältere Browser brauchen einen Rückfall auf setTimeout/clearTimeout.

Siehe auch

DedicatedWorkerGlobalScope.requestAnimationFrame() Window.cancelAnimationFrame() DedicatedWorkerGlobalScope OffscreenCanvas HTMLCanvasElement.transferControlToOffscreen() Worker