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

CKTIS / JavaScript

Événements `load` et `error` d’une image

Gérez la réussite et l’échec du chargement sur l’élément image lui-même. Enregistrez les deux gestionnaires avant de définir `src`, sans prendre `complete` pour une preuve de réussite.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

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() crée un HTMLImageElement, c’est-à-dire un élément <img> qui peut charger une image sans être inséré dans le document. Cette API de navigateur ne fait pas partie d’ECMAScript 2024. Le navigateur déclenche load sur l’élément si la ressource se charge correctement, et error s’il ne peut pas la charger ou l’utiliser, par exemple si l’URL est inaccessible ou si les données sont invalides. L’événement error d’une image n’est ni une exception JavaScript levée ni une réponse contenant un code d’état HTTP.

Écoutez ces événements sur l’image elle-même : ils ne remontent pas dans le DOM et ne sont pas annulables. Enregistrez les deux gestionnaires avec addEventListener() avant d’affecter src. Vous pouvez aussi définir onload et onerror ; une nouvelle affectation remplace le gestionnaire de la propriété concernée. La lecture de src donne une URL, pas le résultat du chargement ni une Promise.

Si une image existante a déjà déclenché un événement, un nouvel écouteur ne le recevra pas rétroactivement. complete ne suffit pas à prouver la réussite : cette propriété peut aussi valoir true si l’image est inutilisable ou si aucune source n’est définie. Pour une image dont la largeur intrinsèque attendue est positive, image.complete && image.naturalWidth > 0 permet de vérifier qu’elle est déjà disponible.

load ne signifie pas que l’image a déjà été affichée. Pour attendre le décodage avant de l’insérer dans le document, utilisez await image.decode() et gérez le rejet de la promesse. Charger une image d’une autre origine ne donne pas à lui seul le droit de lire ses pixels dans un canvas : les restrictions CORS s’appliquent toujours.

Exemples

<!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>

Résultat

load
error

Enregistrez l’exemple dans un fichier `.html`, ouvrez-le dans un navigateur qui autorise les images `data:` sur cette page, puis consultez la console du navigateur. Sans contacter de serveur externe, le code teste d’abord un SVG valide, puis des données d’image invalides. Il utilise une image par essai et retire les deux écouteurs dès qu’il obtient le résultat. Les messages attendus sont `load`, puis `error`.

Leçons associées

  • JavaScript · Leçon 33 · Avancé · Version : 4

Sources