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

CKTIS / JavaScript

HTMLElement.onerror — tratar o evento error

HTMLElement.onerror atribui um processador ao evento error de um elemento, por exemplo, quando falha o carregamento de uma imagem. Não é um mecanismo global para capturar exceções de JavaScript.

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

element.onerror = function (event) { /* handle error */ };
element.onerror = null;

HTMLElement.onerror é a propriedade de processamento do evento error. Num elemento comum, a função recebe um objeto de evento, e não os cinco argumentos associados ao tratamento global de erros.

Atribuir uma função substitui o valor anterior desta propriedade; atribuir null remove esse processador. Para registar funções independentes, utiliza addEventListener('error', handler).

Não confundas esta propriedade com window.onerror: ao comunicar uma exceção, o processador global recebe message, source, lineno, colno, error, e devolver true cancela o evento. Num elemento comum, devolver false só cancela o evento se este for cancelável. As propriedades onerror de body e frameset têm um comportamento especial que encaminha o evento para Window.

O exemplo despacha um evento sintético sem obter recursos. Verifica a invocação e a remoção do processador, não uma falha real de carregamento. Esta é uma API de navegador definida por HTML, não uma funcionalidade da linguagem ECMAScript; o Node 24 não comprova a sua disponibilidade.

Exemplos

(() => {
  const element = document.createElement('img');
  element.onerror = function (event) {
    console.log(`${event.type}: ${event.target === element}`);
  };
  element.dispatchEvent(new Event('error'));
  element.onerror = null;
  element.dispatchEvent(new Event('error'));
})();

Resultado

error: 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