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