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

CKTIS / HTML

onerror — tratar um evento de erro

O atributo onerror contém JavaScript que trata um evento error, por exemplo, quando uma imagem não consegue carregar. Os handlers num elemento diferem de window.onerror nos argumentos e no significado do valor devolvido.

Versão: WHATWG HTML Living Standard; index snapshot date recorded separately

Sintaxe

<img onerror="/* JavaScript using event */" alt="">
element.onerror = function (event) { /* ... */ };
window.onerror = function (message, source, lineno, colno, error) { /* ... */ };

onerror é um atributo de tratamento do evento error. O seu valor é código JavaScript, não um URL. Num elemento comum como img, o código recebe event. A propriedade JavaScript correspondente pode receber uma função ou ser definida como null para remover o handler.

window.onerror tem uma assinatura especial: para um ErrorEvent, recebe message, source, lineno, colno, error. Devolver true só cancela o evento se este for cancelável, impedindo assim que o erro seja comunicado por predefinição. Um ErrorEvent sintético não é cancelável por predefinição, pelo que devolver true não o cancela. Devolver true não retoma a execução do código interrompido. Um handler comum de elemento usa return false para cancelar um evento, se este puder ser cancelado. Uma função de callback passada a addEventListener('error', ...) recebe um único objeto de evento, e o respetivo valor de retorno não cancela o evento.

No elemento body, o atributo onerror trata eventos Window, e não erros locais do elemento body. Não o confunda com o tratamento de erros de recursos em img.

O exemplo envia um evento error sintético, pelo que não precisa de acesso à rede nem de uma falha de carregamento real. Com JavaScript ativado e handlers inline permitidos, o elemento output deverá apresentar error. O teste verifica a invocação do handler, não o carregamento da imagem.

Exemplos

<!doctype html>
<meta charset="utf-8">
<title>onerror</title>
<img id="image" src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" alt="Demo" onerror="document.getElementById('result').textContent = event.type;">
<output id="result"></output>
<script>
  document.getElementById('image').dispatchEvent(new Event('error'));
</script>

Resultado

error

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