OffscreenCanvas: contextrestored — Ereignis · JavaScript-Referenz

Signatur

offscreenCanvas.addEventListener("contextrestored", handler)

Beschreibung

Das Ereignis contextrestored gehört zur Schnittstelle OffscreenCanvas. Es wird ausgelöst, wenn der Browser einen 2D-Kontext (OffscreenCanvasRenderingContext2D) wiederherstellt, der vorher verloren gegangen war. Ein Kontextverlust kann z. B. eintreten, wenn der GPU-Treiber abstürzt oder neu startet, oder wenn der Browser bei Speichermangel GPU-Ressourcen freigibt. Den Verlust meldet vorher das Ereignis contextlost.

Wenn der Kontext wiederhergestellt wird, ist die Zeichenfläche leer und der Zeichenzustand (Transformationen, Füllfarben, Schriften, Clipping) steht wieder auf den Standardwerten. In contextrestored muss die Anwendung darum alle Zustände neu setzen und den Inhalt neu zeichnen. Das Kontext-Objekt selbst bleibt dasselbe. Einen neuen Kontext über getContext() brauchen Sie nicht zu holen.

Registrieren können Sie den Handler mit addEventListener("contextrestored", handler) oder über die Eigenschaft oncontextrestored. Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften, es lässt sich nicht abbrechen und steigt nicht auf (bubbelt nicht). Besonders nützlich ist es in Web Workern, an die ein Canvas mit transferControlToOffscreen() übergeben wurde, denn dort läuft die gesamte Zeichenlogik.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"contextrestored"`.
$handler Pflicht	(event: Event) => void		Callback, der nach der Wiederherstellung aufgerufen wird. Er bekommt ein einfaches `Event`-Objekt.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal` (zum Entfernen über einen `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event mit type === "contextrestored".

Beispiele

Inhalt nach Wiederherstellung neu zeichnen (addEventListener)

const offscreen = new OffscreenCanvas(300, 150);
const ctx = offscreen.getContext("2d");

const draw = () => {
  ctx.fillStyle = "#0a7";
  ctx.fillRect(20, 20, 260, 110);
  ctx.fillStyle = "#fff";
  ctx.font = "20px sans-serif";
  ctx.fillText("Hallo OffscreenCanvas", 40, 85);
};

offscreen.addEventListener("contextlost", () => {
  console.log("Kontext verloren – Zeichnen pausiert");
});

offscreen.addEventListener("contextrestored", () => {
  console.log("Kontext wiederhergestellt – zeichne neu");
  draw(); // Zustand und Inhalt komplett neu aufbauen
});

draw();

Kontext verloren – Zeichnen pausiert Kontext wiederhergestellt – zeichne neu

Im Web Worker mit oncontextrestored und Animationsschleife

// worker.js
let ctx;
let running = false;
let angle = 0;

const frame = () => {
  if (!running) return;
  const { width, height } = ctx.canvas;
  ctx.clearRect(0, 0, width, height);
  ctx.save();
  ctx.translate(width / 2, height / 2);
  ctx.rotate(angle += 0.02);
  ctx.fillStyle = "tomato";
  ctx.fillRect(-40, -40, 80, 80);
  ctx.restore();
  requestAnimationFrame(frame);
};

self.onmessage = ({ data }) => {
  const canvas = data.canvas; // übertragenes OffscreenCanvas
  ctx = canvas.getContext("2d");

  canvas.oncontextlost = () => { running = false; };
  canvas.oncontextrestored = () => {
    running = true;
    requestAnimationFrame(frame);
  };

  running = true;
  requestAnimationFrame(frame);
};

// main.js
// const canvas = document.querySelector("canvas");
// const off = canvas.transferControlToOffscreen();
// new Worker("worker.js").postMessage({ canvas: off }, [off]);

Listener mit AbortController wieder entfernen

const offscreen = new OffscreenCanvas(200, 100);
const ctx = offscreen.getContext("2d");
const controller = new AbortController();

const onRestored = () => {
  ctx.fillStyle = "navy";
  ctx.fillRect(0, 0, 200, 100);
  console.log("neu gezeichnet");
};

offscreen.addEventListener("contextrestored", onRestored, {
  signal: controller.signal
});

// Später, z. B. beim Aufräumen der Komponente:
controller.abort();
// alternativ: offscreen.removeEventListener("contextrestored", onRestored);
console.log("Listener entfernt");

Listener entfernt

// Wichtig · Fallstricke

Browser-Unterstützung: Bisher nur in Chromium-Browsern (Chrome/Edge ab 99). Firefox und Safari unterstützen OffscreenCanvas, lösen aber contextlost/contextrestored für 2D-Kontexte nicht aus. Schreiben Sie Ihren Code deshalb so, dass er auch ohne diese Ereignisse funktioniert.
Leere Zeichenfläche: Nach der Wiederherstellung sind alle Pixel und alle Zustände weg, also fillStyle, font, Transformationen und Clipping. Die Anwendung muss ihren Zeichenzustand selbst speichern, zum Beispiel als Szenenbeschreibung, damit sie ihn neu aufbauen kann.
Wiederherstellung verhindern: Ruft ein contextlost-Handler event.preventDefault() auf, versucht der Browser keine Wiederherstellung. Dann wird auch contextrestored nie ausgelöst.
Mit dem Kontextstatus einer ImageBitmap oder eines ImageData, das vorher aus dem Canvas erzeugt wurde, hat das Ereignis nichts zu tun. Diese Objekte bleiben erhalten und eignen sich zum schnellen Neuzeichnen.
Für WebGL-Kontexte gibt es die eigenen Ereignisse webglcontextlost/webglcontextrestored. Zum Testen eignet sich dort die Erweiterung WEBGL_lose_context. Für 2D-Kontexte gibt es keine vergleichbare Möglichkeit, den Verlust gezielt auszulösen.
Den aktuellen Status können Sie mit ctx.isContextLost() abfragen (ebenfalls nur in Chromium).

Siehe auch

OffscreenCanvas OffscreenCanvas: contextlost OffscreenCanvasRenderingContext2D HTMLCanvasElement: contextrestored HTMLCanvasElement.transferControlToOffscreen() EventTarget.addEventListener() LanguageModel: contextoverflow