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

CKTIS / JavaScript

Imagens em JavaScript: `src`, `alt`, `load` e `error`

Define o URL e o texto alternativo de uma imagem e usa eventos do elemento para reagir ao sucesso ou à falha do carregamento.

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

Sintaxe

const img = new Image();
img.alt = text;
img.addEventListener("load", onLoad);
img.addEventListener("error", onError);

// To use handler properties, replace the two listener registrations above with:
// img.onload = onLoad;
// img.onerror = onError;

img.src = url;

new Image() cria um elemento img do tipo HTMLImageElement, inicialmente fora da árvore do documento. Esta API faz parte da plataforma Web, não de ECMAScript 2024. O ambiente de execução tem de a disponibilizar.

img.src é uma propriedade de texto que reflete o atributo src. A atribuição inicia o processamento assíncrono da origem, mesmo sem inserir o elemento no documento. Ao ler img.src, um URL relativo válido é resolvido em relação ao URL base do documento; img.getAttribute("src") devolve o valor guardado no atributo. Com imagens adaptáveis, consulta img.currentSrc para saber que URL o navegador selecionou.

img.alt reflete o atributo alt. Escreve um texto que transmita o significado ou a função da imagem no seu contexto a quem não a pode ver. Se for meramente decorativa, usa alt = "" em vez de omitir o atributo. alt não é o URL de uma imagem de substituição.

load indica que a imagem foi carregada com sucesso; error indica que não foi possível carregar ou utilizar o recurso escolhido. São eventos do elemento, não métodos nem exceções capturadas por um try...catch à volta da atribuição a src. Regista ambos os ouvintes antes de definir src. Em alternativa, atribui funções de tratamento a onload e onerror: uma nova atribuição substitui a função dessa propriedade.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Image load and error events</title>
</head>
<body>
<script>
(async () => {
  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10"><circle cx="5" cy="5" r="5" fill="blue"/></svg>';
  const valid = 'data:image/svg+xml,' + encodeURIComponent(svg);
  const invalid = 'data:image/svg+xml,not-an-svg';

  function reportImage(url) {
    return new Promise((resolve) => {
      const img = new Image();
      img.alt = 'Blue dot';
      const report = (event) => {
        console.log(`${event.type}: ${img.alt}`);
        resolve();
      };
      img.addEventListener('load', report, { once: true });
      img.addEventListener('error', report, { once: true });
      img.src = url;
    });
  }

  await reportImage(valid);
  await reportImage(invalid);
})();
</script>
</body>
</html>

Resultado

load: Blue dot
error: Blue dot

Guarda o exemplo como ficheiro HTML, abre-o num navegador e consulta o resultado na consola de programador. O código testa um SVG válido e depois dados de imagem inválidos, sem pedidos de rede. Ambas as linhas indicam o evento e o valor inalterado de `alt`; não mostram como o navegador apresenta o texto alternativo. Uma política de segurança de conteúdos (CSP) que bloqueie imagens `data:` pode também provocar `error` no primeiro teste.

Lições relacionadas

  • JavaScript · Lição 30 · Intermédio · Versão: 3

Fontes