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

CKTIS / JavaScript

Images en JavaScript : `src`, `alt`, `load` et `error`

Définissez l’URL et le texte alternatif d’une image, puis réagissez à la réussite ou à l’échec du chargement avec les événements de l’élément.

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

Syntaxe

const img = new Image();
img.alt = text;
img.addEventListener("load", onLoad);
img.addEventListener("error", onError);

// To use handler properties, replace the two listener registrations above with:
// img.onload = onLoad;
// img.onerror = onError;

img.src = url;

new Image() crée un élément img de type HTMLImageElement, initialement hors de l’arbre du document. Cette API fait partie de la plateforme web, pas d’ECMAScript 2024. L’environnement d’exécution doit la fournir.

img.src est une propriété de type chaîne qui reflète l’attribut src. L’affectation lance le traitement asynchrone de la source, même si l’élément n’a pas été inséré dans le document. À la lecture, img.src résout une URL relative valide par rapport à l’URL de base du document ; img.getAttribute("src") renvoie la valeur stockée de l’attribut. Avec les images adaptatives, img.currentSrc indique l’URL choisie par le navigateur.

img.alt reflète l’attribut alt. Rédigez un texte qui transmet aux personnes qui ne voient pas l’image son sens ou sa fonction dans le contexte. Si l’image est purement décorative, utilisez alt = "" plutôt que d’omettre l’attribut. alt n’est pas l’URL d’une image de remplacement.

load signale un chargement réussi ; error indique que la ressource sélectionnée n’a pas pu être chargée ou utilisée. Ce sont des événements de l’élément, pas des méthodes ni des exceptions qu’un try...catch autour de l’affectation à src intercepterait. Ajoutez les deux écouteurs avant de définir src. Vous pouvez aussi affecter des gestionnaires à onload et onerror ; une nouvelle affectation remplace le gestionnaire de la propriété concernée.

Exemples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Image load and error events</title>
</head>
<body>
<script>
(async () => {
  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10"><circle cx="5" cy="5" r="5" fill="blue"/></svg>';
  const valid = 'data:image/svg+xml,' + encodeURIComponent(svg);
  const invalid = 'data:image/svg+xml,not-an-svg';

  function reportImage(url) {
    return new Promise((resolve) => {
      const img = new Image();
      img.alt = 'Blue dot';
      const report = (event) => {
        console.log(`${event.type}: ${img.alt}`);
        resolve();
      };
      img.addEventListener('load', report, { once: true });
      img.addEventListener('error', report, { once: true });
      img.src = url;
    });
  }

  await reportImage(valid);
  await reportImage(invalid);
})();
</script>
</body>
</html>

Résultat

load: Blue dot
error: Blue dot

Enregistrez l’exemple dans un fichier HTML, ouvrez-le dans un navigateur et consultez le résultat dans la console de développement. Le code teste successivement un SVG valide et des données d’image invalides, sans requête réseau. Les deux lignes indiquent l’événement et la valeur inchangée de `alt` ; elles ne montrent pas comment le navigateur affiche le texte alternatif. Une politique de sécurité du contenu (CSP) qui bloque les images `data:` peut aussi déclencher `error` au premier test.

Leçons associées

  • JavaScript · Leçon 30 · Intermédiaire · Version : 3

Sources