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

CKTIS / HTML

oncontextrestored — tratar o restauro do contexto do canvas

O atributo oncontextrestored especifica o código que trata o evento contextrestored. Num canvas com um contexto 2D, o evento assinala o restauro após a perda do contexto; a aplicação deve então reconstruir as definições de desenho e o conteúdo.

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

Sintaxe

<canvas oncontextrestored="/* JavaScript using event */"></canvas>
canvas.oncontextrestored = (event) => { /* handle restoration */ };
canvas.addEventListener("contextrestored", handler);

oncontextrestored é um atributo HTML de tratamento de eventos e uma propriedade JavaScript correspondente de GlobalEventHandlers. O nome do evento é contextrestored, sem o prefixo on. Em HTML, o valor do atributo é código JavaScript com o parâmetro event disponível; à propriedade JavaScript é atribuída uma função ou null. addEventListener("contextrestored", handler) é uma alternativa que permite registar vários ouvintes.

O navegador envia este evento para o canvas depois de restaurar com êxito um contexto 2D perdido. A perda do contexto repõe o estado de desenho, pelo que o respetivo tratamento deve voltar a aplicar os estilos e as transformações necessários e redesenhar a cena a partir dos dados da aplicação. Não assuma que os píxeis anteriores são recuperados automaticamente. A atribuição de um controlador não restaura o contexto por si só, nem garante que o restauro seja bem-sucedido.

O exemplo verifica apenas a ligação do atributo, enviando um evento sintético. O valor de event.isTrusted é false; isto não testa a perda nem a recuperação efetiva do contexto. Execute-o num navegador que suporte a propriedade e permita scripts inline.

Exemplos

<!doctype html>
<meta charset="utf-8">
<title>oncontextrestored test</title>
<canvas id="surface" width="80" height="40"
  oncontextrestored="console.log(event.type, event.isTrusted)"></canvas>
<script>
  const canvas = document.getElementById("surface");
  if (!("oncontextrestored" in canvas)) {
    throw new Error("oncontextrestored is not supported");
  }
  canvas.dispatchEvent(new Event("contextrestored"));
</script>

Resultado

contextrestored 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