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