HTMLImageElement : méthode decode()

Syntaxe

decode()

Paramètres

Aucun.

Valeur de retour

Une promesse Promise qui se résout avec undefined lorsque les données de l'image sont prêtes à être utilisées.

Exceptions

EncodingError

Un DOMException indiquant qu'une erreur est survenue lors du décodage de l'image.

Notes d'utilisation

Un cas d'usage courant pour decode() : lors du chargement d'images très volumineuses (par exemple dans un album photo en ligne), vous pouvez d'abord afficher une miniature basse résolution, puis la remplacer par l'image en pleine résolution en instanciant un nouveau HTMLImageElement, en définissant sa source sur l'URL de l'image haute résolution, puis en utilisant decode() pour obtenir une promesse qui sera résolue lorsque l'image haute résolution sera prête à l'emploi. À ce moment-là, vous pouvez remplacer la miniature par l'image haute résolution désormais disponible.

Exemples

Utilisation simple

L'exemple suivant montre comment utiliser la méthode decode() pour contrôler le moment où une image est ajoutée au DOM.

const img = new Image();
img.src = "nebula.jpg";
img
  .decode()
  .then(() => {
    document.body.appendChild(img);
  })
  .catch((encodingError) => {
    // Do something with the error.
  });

Éviter les images vides

Dans l'exemple ci-dessous, vous obtiendrez probablement une image vide affichée sur la page pendant le téléchargement de l'image :

const img = new Image();
img.src = "img/logo.png";
document.body.appendChild(img);

L'utilisation de decode() permet de retarder l'insertion de l'image dans le DOM jusqu'à ce qu'elle soit entièrement téléchargée et décodée, évitant ainsi le problème d'image vide :

async function getImage() {
  const img = new Image();
  img.src = "img/logo.png";
  await img.decode();
  document.body.appendChild(img);
  const p = document.createElement("p");
  p.textContent = "L'image est complètement chargée !";
  document.body.appendChild(p);
}

Ceci est particulièrement utile si vous remplacez dynamiquement une image existante par une nouvelle, et cela évite également que des rendus non liés à ce code soient bloqués pendant le décodage de l'image.

Spécifications

Compatibilité des navigateurs

Voir aussi

• Que fait réellement l'attribut de décodage d'image ? ^(angl.) sur tunetheweb.com (2023)
• La propriété HTMLImageElement.decoding