Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / HTML

oncontextlost — gestire la perdita del contesto canvas

L’attributo oncontextlost specifica il codice che gestisce l’evento contextlost, inviato quando si perde il contesto di rendering 2D di un elemento canvas. Consente a un’applicazione di reagire alla perdita di risorse, ma non ripristina il disegno da solo.

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

Sintassi

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

oncontextlost è un attributo globale per la gestione dell’evento contextlost. In pratica, si usa su un elemento canvas il cui contesto 2D ha perso l’archiviazione dell’immagine. Il valore dell’attributo è codice JavaScript, non un valore booleano; il codice riceve l’oggetto event.

In JavaScript puoi assegnare una funzione alla proprietà canvas.oncontextlost. In alternativa, usa canvas.addEventListener('contextlost', handler). Anche OffscreenCanvas espone una proprietà oncontextlost, ma non è un elemento HTML e non ha attributi di markup. Non confondere questo evento con l’evento WebGL webglcontextlost.

In caso di effettiva perdita del contesto, il browser reimposta lo stato di rendering. L’evento contextlost è annullabile: event.preventDefault() interrompe il tentativo di ripristino del contesto descritto dallo standard; non chiamare questo metodo se vuoi consentire il tentativo. Il ripristino non è garantito. Dopo contextrestored, l’applicazione dovrebbe reimpostare lo stato necessario e ridisegnare il contenuto.

L’esempio invia un evento sintetico, quindi funziona senza provocare un errore grafico. L’output contextlost: false mostra il tipo di evento e il valore di event.isTrusted. Il test verifica solo la gestione dell’evento, non la perdita di risorse né il loro ripristino.

Esempi

<!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>

Risultato

contextlost: false

Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.

Fonti