WebGLContextEvent.statusMessage — Eigenschaft · JavaScript-Referenz

Signatur

WebGLContextEvent.statusMessage

Beschreibung

Die schreibgeschützte Eigenschaft statusMessage eines WebGLContextEvent enthält einen vom Browser festgelegten Text mit zusätzlichen Informationen zum Ereignis. Gibt es keine weiteren Informationen, ist der Wert ein leerer String ("").

Besonders nützlich ist die Eigenschaft beim Ereignis webglcontextcreationerror. Es wird ausgelöst, wenn canvas.getContext("webgl") bzw. "webgl2" keinen Kontext erzeugen kann, etwa weil die Grafikkarte auf einer Sperrliste steht, Hardwarebeschleunigung abgeschaltet ist oder der Treiber abstürzt. Dann steht in statusMessage oft der Grund, zum Beispiel „Web page caused context loss and was blocked“.

Bei webglcontextlost und webglcontextrestored ist der Wert in der Praxis meistens leer. Verwenden Sie die Eigenschaft deshalb für Diagnose, Protokollierung und Fehlerberichte, aber nicht für die Programmlogik. Inhalt und Formulierung hängen vom Browser ab und sind nicht standardisiert.

Rückgabewert

Typ

string

Beschreibung

Ein vom Browser festgelegter Hinweistext zum Ereignisstatus oder ein leerer String, wenn keine zusätzlichen Informationen verfügbar sind.

Beispiele

Grund für fehlgeschlagene Kontext-Erstellung ausgeben

const canvas = document.createElement('canvas');

// Listener VOR getContext() registrieren – das Ereignis wird synchron ausgelöst
canvas.addEventListener('webglcontextcreationerror', (event) => {
  console.warn('WebGL nicht verfügbar:', event.statusMessage || '(kein Grund angegeben)');
}, { once: true });

const gl = canvas.getContext('webgl2') ?? canvas.getContext('webgl');
if (!gl) {
  console.log('Fallback auf Canvas 2D');
}

WebGL nicht verfügbar: Web page caused context loss and was blocked Fallback auf Canvas 2D

Kontextverlust protokollieren und Wiederherstellung erlauben

const canvas = document.querySelector('#scene');
const gl = canvas.getContext('webgl');

canvas.addEventListener('webglcontextlost', (event) => {
  event.preventDefault(); // ohne preventDefault() keine Wiederherstellung
  console.log('Kontext verloren. Status:', JSON.stringify(event.statusMessage));
});

canvas.addEventListener('webglcontextrestored', () => {
  console.log('Kontext wiederhergestellt – Ressourcen neu anlegen');
});

// Zum Testen einen Verlust simulieren
const ext = gl.getExtension('WEBGL_lose_context');
ext?.loseContext();
setTimeout(() => ext?.restoreContext(), 1000);

Kontext verloren. Status: "" Kontext wiederhergestellt – Ressourcen neu anlegen

Eigenes Ereignis mit statusMessage erzeugen

const event = new WebGLContextEvent('webglcontextlost', {
  statusMessage: 'GPU-Speicher erschöpft (Test)'
});

console.log(event.type);
console.log(event.statusMessage);

event.statusMessage = 'geändert'; // wird ignoriert, da schreibgeschützt
console.log(event.statusMessage);

webglcontextlost GPU-Speicher erschöpft (Test) GPU-Speicher erschöpft (Test)

// Wichtig · Fallstricke

Nicht standardisierter Inhalt: Der Text hängt von Browser, Treiber und Sprache ab. Werten Sie ihn nicht mit Stringvergleichen aus, sondern verwenden Sie ihn nur zur Anzeige oder Protokollierung.
Häufig leer: Bei webglcontextlost und webglcontextrestored liefern die meisten Browser "". Sehen Sie deshalb immer einen Ersatztext vor, etwa mit event.statusMessage || 'unbekannt'.
Reihenfolge beachten: webglcontextcreationerror wird synchron während getContext() ausgelöst. Registrieren Sie den Listener deshalb vorher, sonst verpassen Sie das Ereignis.
Schreibgeschützt: Eine Zuweisung wird ignoriert, im Strict Mode löst sie einen TypeError aus. Einen eigenen Wert können Sie nur über das Initialisierungsobjekt des Konstruktors setzen.
Datenschutz: Die Meldung kann Hinweise auf GPU oder Treiber enthalten. Prüfen Sie, ob Sie sie an Fehlerdienste weitergeben dürfen.
Kompatibilität: Wird in allen aktuellen Browsern mit WebGL unterstützt, auch in Web Workern mit OffscreenCanvas.

Siehe auch

WebGLContextEvent HTMLCanvasElement.getContext() ErrorEvent.message BlobEvent.timecode FontFaceSet.status