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

CKTIS / JavaScript

HTMLImageElement: carregamento de imagens, dimensões e estado complete

HTMLImageElement permite definir a origem e o texto alternativo de uma imagem, tratar os eventos load e error e consultar as dimensões naturais. A propriedade complete não comprova o sucesso: também é true para uma imagem danificada ou um elemento sem origem.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

const image = new Image();
image.alt = description;
image.addEventListener("load", onLoad, { once: true });
image.addEventListener("error", onError, { once: true });
image.src = url;
// Read: image.naturalWidth, image.naturalHeight, image.complete

HTMLImageElement representa um elemento de imagem; new Image() cria um sem o adicionar ao documento. HTMLImageElement.src define o URL do recurso e HTMLImageElement.alt define o texto alternativo. Forneça uma descrição significativa para uma imagem informativa; use um alt vazio para uma imagem decorativa.

HTMLImageElement.load e HTMLImageElement.error designam aqui os eventos load e error, não métodos que se possam chamar. O primeiro indica um carregamento bem-sucedido; o segundo, uma falha de carregamento ou de apresentação. Registe ambos os ouvintes com addEventListener antes de atribuir src, para que um carregamento rápido não termine antes do registo.

As propriedades só de leitura HTMLImageElement.naturalWidth e HTMLImageElement.naturalHeight indicam as dimensões intrínsecas corrigidas pela densidade, em píxeis CSS, e não o tamanho imposto pelos estilos. Uma dimensão indisponível tem o valor 0. HTMLImageElement.complete é só de leitura: pode ser true após sucesso, após falha, sem origem ou com um src vazio. Por isso, complete por si só não comprova o sucesso.

Para um elemento existente, registe primeiro ambos os ouvintes e depois verifique o estado atual. Se o elemento não tiver origem, trate esse caso separadamente, mas lembre-se de que um elemento picture que o contenha pode fornecer uma origem. Se o elemento tiver origem e complete for false, aguarde por load ou error. A condição complete && naturalWidth > 0 não comprova que o carregamento tenha sido bem-sucedido. Num img sem atributos próprios src e srcset, complete pode ter o valor true enquanto a imagem fornecida pelo picture que o contém ainda está a ser carregada. naturalWidth pode assumir um valor positivo assim que as dimensões estiverem disponíveis, antes de o carregamento terminar. Se complete && naturalWidth === 0, estas propriedades também não permitem determinar o resultado: uma imagem sem largura intrínseca pode ser carregada com sucesso. Não a considere indisponível com base nessa condição. Se já registou um evento load ou error para o pedido atual da imagem, utilize esse resultado. Um ouvinte acabado de registar não recebe um evento que já tenha sido disparado. Garanta que a verificação do estado e os ouvintes não tratam o mesmo resultado duas vezes.

Esta é uma API do navegador definida por HTML, não uma funcionalidade de uma edição específica de ECMAScript. Os mecanismos básicos descritos são amplamente suportados; a presença de Node 24 num repositório não comprova a disponibilidade de uma API do navegador. O exemplo cria em memória uma imagem SVG decorativa sem a adicionar ao documento. O SVG tem uma largura e uma altura positivas definidas explicitamente, pelo que o exemplo não mostra um carregamento bem-sucedido sem largura intrínseca.

Exemplos

(() => {
  const image = new Image();
  image.alt = "";

  image.addEventListener("load", () => {
    console.log(`load: ${image.naturalWidth}x${image.naturalHeight}; complete=${image.complete}`);
  }, { once: true });

  image.addEventListener("error", () => {
    console.log("error: image unavailable");
  }, { once: true });

  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="2" height="3"><rect width="2" height="3" fill="blue"/></svg>';
  image.src = `data:image/svg+xml,${encodeURIComponent(svg)}`;
})();

Resultado

load: 2x3; complete=true

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