Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / HTML

oncontextlost — lidar com a perda do contexto do canvas

O atributo oncontextlost especifica o código que trata o evento contextlost, enviado quando se perde o contexto de desenho 2D de um elemento canvas. Permite que uma aplicação reaja à perda de recursos, mas não restaura o desenho por si só.

Versão: WHATWG HTML Living Standard; index snapshot date recorded separately

Sintaxe

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

oncontextlost é um atributo global de tratamento do evento contextlost. Na prática, é usado num elemento canvas cujo contexto 2D perdeu o armazenamento da imagem. O valor do atributo é código JavaScript, não um valor booleano; o código recebe o objeto event.

Em JavaScript, pode atribuir uma função à propriedade canvas.oncontextlost. Em alternativa, use canvas.addEventListener('contextlost', handler). OffscreenCanvas também expõe uma propriedade oncontextlost, mas não é um elemento HTML e não tem atributos de marcação. Não confunda este evento com o evento WebGL webglcontextlost.

Quando ocorre uma perda real do contexto, o navegador repõe o estado de desenho. O evento contextlost pode ser cancelado: event.preventDefault() interrompe a tentativa de restauro do contexto descrita pela norma; não chame este método se quiser permitir essa tentativa. O restauro não é garantido. Após contextrestored, a aplicação deve voltar a aplicar o estado necessário e redesenhar o conteúdo.

O exemplo envia um evento sintético, pelo que funciona sem provocar uma falha gráfica. A saída contextlost: false mostra o tipo de evento e o valor de event.isTrusted. Este teste verifica apenas o tratamento do evento, não a perda de recursos nem o seu restauro.

Exemplos

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

Resultado

contextlost: false

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes