WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / HTML

oncontextlost – Umgang mit dem Verlust des Canvas-Kontexts

Das Attribut oncontextlost legt den Code fest, der das Ereignis contextlost behandelt. Es wird ausgelöst, wenn der 2D-Rendering-Kontext eines canvas-Elements verloren geht. So kann eine Anwendung auf den Verlust von Ressourcen reagieren, die Zeichnung wird dadurch jedoch nicht selbst wiederhergestellt.

Version: WHATWG HTML Living Standard; index snapshot date recorded separately

Syntax

<canvas oncontextlost="handler(event)"></canvas>
canvas.oncontextlost = handler;

oncontextlost ist ein globales Ereignisbehandlungsattribut für contextlost. In der Praxis wird es auf einem canvas-Element verwendet, dessen 2D-Kontext seinen Speicher für die Bilddaten verloren hat. Der Attributwert ist JavaScript-Code, kein boolescher Wert; der Code erhält das Objekt event.

In JavaScript kannst du der Eigenschaft canvas.oncontextlost eine Funktion zuweisen. Alternativ kannst du canvas.addEventListener('contextlost', handler) verwenden. Auch OffscreenCanvas stellt eine Eigenschaft oncontextlost bereit, ist aber kein HTML-Element und hat keine Markup-Attribute. Verwechsle dieses Ereignis nicht mit dem WebGL-Ereignis webglcontextlost.

Bei einem tatsächlichen Verlust des Kontexts setzt der Browser den Rendering-Zustand zurück. Das Ereignis contextlost ist abbrechbar: event.preventDefault() verhindert den im Standard beschriebenen Versuch, den Kontext wiederherzustellen. Rufe diese Methode nicht auf, wenn du diesen Versuch ermöglichen möchtest. Eine Wiederherstellung ist nicht garantiert. Nach contextrestored sollte die Anwendung den benötigten Zustand erneut festlegen und ihren Inhalt neu zeichnen.

Das Beispiel löst ein synthetisches Ereignis aus und funktioniert daher, ohne einen Grafikfehler zu verursachen. Die Ausgabe contextlost: false zeigt den Ereignistyp und den Wert von event.isTrusted. Damit wird nur die Ereignisbehandlung getestet, nicht der Ressourcenverlust oder die Wiederherstellung.

Beispiele

<!doctype html>
<meta charset="utf-8">
<title>oncontextlost test</title>
<canvas id="surface" oncontextlost="document.getElementById('result').textContent = event.type + ': ' + event.isTrusted"></canvas>
<pre id="result">waiting</pre>
<script>
  document.getElementById('surface').dispatchEvent(
    new Event('contextlost', { cancelable: true })
  );
</script>

Ergebnis

contextlost: false

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen