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

CKTIS / JavaScript

Eventos `load` e `error` de uma imagem

Trata o sucesso e a falha do carregamento no próprio elemento de imagem. Regista os dois processadores antes de definir `src` e não interpretes `complete` como prova de sucesso.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

const image = new Image();
image.addEventListener("load", onLoad);
image.addEventListener("error", onError);
image.src = url;

// Alternative to addEventListener():
// image.onload = onLoad;
// image.onerror = onError;

new Image() cria um HTMLImageElement, ou seja, um elemento <img> que pode carregar uma imagem sem ser inserido no documento. Trata-se de uma API do navegador, não de uma funcionalidade de ECMAScript 2024. O navegador dispara load no elemento se o recurso for carregado com sucesso, e error se não o conseguir carregar ou utilizar, por exemplo, por o URL estar inacessível ou os dados da imagem serem inválidos. O evento error da imagem não é uma exceção lançada em JavaScript nem uma resposta com um código de estado HTTP.

Escuta os eventos na própria imagem: nenhum se propaga para os antepassados na fase de bubbling e nenhum pode ser cancelado. Regista os dois processadores com addEventListener() antes de atribuíres src. Em alternativa, define onload e onerror; uma nova atribuição substitui o processador da propriedade em causa. Ler src devolve um URL, não o resultado do carregamento nem uma Promise.

Se uma imagem existente já tiver disparado um evento, um novo listener não o recebe retroativamente. complete não basta para confirmar o sucesso: também pode valer true se a imagem estiver inutilizável ou não tiver uma fonte definida. Para uma imagem cuja largura intrínseca esperada seja positiva, image.complete && image.naturalWidth > 0 permite verificar se já está disponível.

load não significa que a imagem já tenha sido desenhada no ecrã. Se precisares de esperar pela descodificação antes de a inserir no documento, usa await image.decode() e trata a rejeição da promessa. O carregamento bem-sucedido de uma imagem de outra origem não permite, por si só, ler os seus píxeis a partir de um canvas; as restrições CORS continuam a aplicar-se.

Exemplos

<!doctype html>
<meta charset="utf-8">
<title>Image load and error events</title>
<script>
(async () => {
  function imageOutcome(url) {
    return new Promise((resolve) => {
      const image = new Image();
      function finish(event) {
        image.removeEventListener("load", finish);
        image.removeEventListener("error", finish);
        resolve(event.type);
      }
      image.addEventListener("load", finish);
      image.addEventListener("error", finish);
      image.src = url;
    });
  }

  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"><rect width="1" height="1"/></svg>';
  const dataURL = (text) => `data:image/svg+xml,${encodeURIComponent(text)}`;
  console.log(await imageOutcome(dataURL(svg)));
  console.log(await imageOutcome(dataURL("not an SVG")));
})();
</script>

Resultado

load
error

Guarda o exemplo como um ficheiro `.html`, abre-o num navegador que permita imagens `data:` nessa página e consulta a consola do navegador. Sem contactar um servidor externo, o código testa primeiro um SVG válido e depois dados de imagem inválidos. Usa uma imagem distinta por tentativa e remove os dois listeners quando recebe o resultado. As mensagens esperadas são `load` e depois `error`.

Lições relacionadas

  • JavaScript · Lição 33 · Avançado · Versão: 4

Fontes