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.