HTMLCanvasElement: contextlost — Ereignis · JavaScript-Referenz

Signatur

canvas.addEventListener("contextlost", handler)

Beschreibung

Das Ereignis contextlost wird an einem HTMLCanvasElement (und an OffscreenCanvas) ausgelöst, wenn der Browser feststellt, dass der Speicher hinter einem 2D-Kontext verloren gegangen ist. Das passiert vor allem bei hardwarebeschleunigten Canvas-Elementen, z. B. nach einem Absturz oder Reset des Grafiktreibers, bei zu wenig GPU-Speicher oder wenn das System Ressourcen von Hintergrund-Tabs zurückfordert. Danach ist der Inhalt des Canvas weg und Zeichenbefehle bewirken nichts mehr.

Sie können das Ereignis mit addEventListener("contextlost", …) oder über die Eigenschaft canvas.oncontextlost abfangen. Es ist ein einfaches Event ohne weitere Eigenschaften. Es bubbelt nicht, lässt sich aber abbrechen (cancelable: true). Solange der Kontext verloren ist, liefert ctx.isContextLost() den Wert true.

Standardverhalten: Der Browser versucht selbstständig, den Kontext wiederherzustellen. Wenn das klappt, wird contextrestored ausgelöst. Dann ist der Kontext wieder zurückgesetzt (leer, Standardzustand), und Ihre Anwendung muss alles neu zeichnen und Zustände wie fillStyle, Transformationen usw. neu setzen. Wenn Sie in contextlost event.preventDefault() aufrufen, versucht der Browser keine Wiederherstellung.

Typische Einsätze sind: Animationsschleifen anhalten, einen Hinweis anzeigen und die Szene aus dem eigenen Anwendungszustand neu aufbauen. Speichern Sie deshalb den Zustand Ihrer Grafik immer getrennt vom Canvas, denn Pixeldaten im Canvas gehen beim Kontextverlust verloren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier `"contextlost"`.
$handler Pflicht	(event: Event) => void		Callback, der beim Kontextverlust aufgerufen wird. Er bekommt ein einfaches `Event`, das sich abbrechen lässt.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once`, `passive` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Mit event.preventDefault() im Handler verhindern Sie, dass der Browser den Kontext automatisch wiederherstellt.

Beispiele

Kontextverlust erkennen und nach Wiederherstellung neu zeichnen

const canvas = document.querySelector('#chart');
const ctx = canvas.getContext('2d');

// Anwendungszustand getrennt vom Canvas halten
const daten = [12, 40, 25, 60, 33];
let frameId = null;

const zeichnen = () => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.fillStyle = '#3366cc';
  daten.forEach((wert, i) => {
    ctx.fillRect(i * 50 + 10, canvas.height - wert * 2, 40, wert * 2);
  });
  frameId = requestAnimationFrame(zeichnen);
};

canvas.addEventListener('contextlost', () => {
  console.warn('Canvas-Kontext verloren – Animation pausiert');
  cancelAnimationFrame(frameId);
});

canvas.addEventListener('contextrestored', () => {
  console.info('Kontext wiederhergestellt – zeichne neu');
  zeichnen(); // Zustand (fillStyle etc.) wird in zeichnen() neu gesetzt
});

zeichnen();

Canvas-Kontext verloren – Animation pausiert Kontext wiederhergestellt – zeichne neu

Über die on-Property: Wiederherstellung unterbinden

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

canvas.oncontextlost = (event) => {
  // Keine automatische Wiederherstellung – eigene Fehlerbehandlung
  event.preventDefault();
  console.log('Verloren:', ctx.isContextLost());
  canvas.replaceWith(
    Object.assign(document.createElement('p'), {
      textContent: 'Grafik nicht verfügbar. Bitte Seite neu laden.'
    })
  );
};

// Handler später wieder entfernen
// canvas.oncontextlost = null;

Verloren: true

Listener mit AbortController sauber entfernen

const canvas = document.querySelector('canvas');
const controller = new AbortController();

const beiVerlust = () => console.warn('contextlost auf', canvas.id);

canvas.addEventListener('contextlost', beiVerlust, { signal: controller.signal });

// Beim Abbau der Komponente alle Listener entfernen
const zerstoeren = () => {
  controller.abort();
  // Alternativ: canvas.removeEventListener('contextlost', beiVerlust);
};

zerstoeren();

// Wichtig · Fallstricke

Browserunterstützung: contextlost, contextrestored und isContextLost() für 2D-Kontexte gibt es in Chromium-Browsern ab Version 99. In anderen Engines fehlen sie teilweise. Prüfen Sie deshalb vorher, z. B. mit 'oncontextlost' in canvas oder typeof ctx.isContextLost === 'function'.
Anders als bei WebGL: Bei webglcontextlost müssen Sie preventDefault() aufrufen, damit eine Wiederherstellung möglich ist. Bei contextlost (2D) ist es umgekehrt: preventDefault() verhindert die Wiederherstellung.
Nach contextrestored ist der Kontext komplett zurückgesetzt, also ohne Pixel, Transformationen, Stile oder Clipping. Pixeldaten, die Sie nur im Canvas gespeichert haben, sind endgültig verloren.
Das Ereignis bubbelt nicht. Hängen Sie den Listener deshalb direkt an das Canvas-Element und nicht an einen Container.
Kontextverlust lässt sich schwer nachstellen. In Chrome können Sie über chrome://gpucrash einen GPU-Absturz auslösen und so den Ablauf testen.

Siehe auch

HTMLCanvasElement: contextrestored CanvasRenderingContext2D.isContextLost() HTMLCanvasElement: webglcontextlost HTMLCanvasElement.getContext() OffscreenCanvas CanvasRenderingContext2D HTMLElement: loseinterest