Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

HTMLElement.onerror — gérer l’événement error

HTMLElement.onerror associe un gestionnaire à l’événement error d’un élément, par exemple en cas d’échec du chargement d’une image. Ce n’est pas un mécanisme global de capture des exceptions JavaScript.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

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

HTMLElement.onerror est la propriété de gestionnaire d’événement pour error. Sur un élément ordinaire, sa fonction reçoit un objet événement, et non les cinq arguments associés à la gestion globale des erreurs.

L’affectation d’une fonction remplace la valeur précédente de cette propriété ; l’affectation de null supprime ce gestionnaire. Pour enregistrer des fonctions indépendantes, utilise addEventListener('error', handler).

Ne confonds pas cette propriété avec window.onerror : lors du signalement d’une exception, le gestionnaire global reçoit message, source, lineno, colno, error, et renvoyer true annule l’événement. Sur un élément ordinaire, renvoyer false n’annule l’événement que s’il peut être annulé. Les propriétés onerror de body et frameset ont un comportement particulier de transfert vers Window.

L’exemple déclenche un événement synthétique sans récupérer de ressources. Il vérifie l’appel et la suppression du gestionnaire, et non un véritable échec de chargement. Il s’agit d’une API de navigateur définie par HTML, et non d’une fonctionnalité du langage ECMAScript ; Node 24 ne permet pas d’établir sa disponibilité.

Exemples

(() => {
  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'));
})();

Résultat

error: true

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources