Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / HTML

oncontextlost — gérer la perte du contexte du canvas

L’attribut oncontextlost définit le code qui gère l’événement contextlost, déclenché lorsque le contexte de rendu 2D d’un élément canvas est perdu. Il permet à une application de réagir à la perte de ressources, mais ne restaure pas le dessin lui-même.

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

Syntaxe

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

oncontextlost est un attribut global de gestion de l’événement contextlost. En pratique, il s’utilise sur un élément canvas dont le contexte 2D a perdu son stockage d’image. La valeur de l’attribut est du code JavaScript, et non une valeur booléenne ; ce code reçoit l’objet event.

En JavaScript, vous pouvez affecter une fonction à la propriété canvas.oncontextlost. Vous pouvez aussi utiliser canvas.addEventListener('contextlost', handler). OffscreenCanvas expose également une propriété oncontextlost, mais ce n’est pas un élément HTML et il n’a pas d’attributs de balisage. Ne confondez pas cet événement avec l’événement WebGL webglcontextlost.

Lors d’une véritable perte du contexte, le navigateur réinitialise l’état de rendu. L’événement contextlost peut être annulé : event.preventDefault() arrête la tentative de restauration du contexte décrite par la norme ; ne l’appelez pas si vous souhaitez autoriser cette tentative. La restauration n’est pas garantie. Après contextrestored, l’application doit réappliquer l’état nécessaire et redessiner son contenu.

L’exemple déclenche un événement synthétique et fonctionne donc sans provoquer de défaillance graphique. La sortie contextlost: false indique le type d’événement et la valeur de event.isTrusted. Ce test porte uniquement sur la gestion de l’événement, pas sur la perte de ressources ni leur restauration.

Exemples

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

Résultat

contextlost: false

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources