HTMLImageElement

Baseline Widely available *

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis ⁨juillet 2015⁩.

* Certaines parties de cette fonctionnalité peuvent bénéficier de prise en charge variables.

L'interfaceHTMLImageElement représente un élément HTML<img>, fournissant les propriétés et méthodes utilisées pour manipuler les éléments image.

Constructeur

Image(): Le constructeurImage() crée et retourne un nouvel objetHTMLImageElement représentant un élément HTML<img> qui n'est pas attaché à un arbre DOM. Il accepte des paramètres optionnels de largeur et de hauteur. Appelé sans paramètre,new Image() est équivalent àdocument.createElement('img').

Propriétés d'instance

Hérite des propriétés de son parent,HTMLElement.

HTMLImageElement.alt: Une chaîne de caractères qui reflète l'attribut HTMLalt, indiquant le contenu de remplacement à afficher si l'image n'a pas été chargée.
HTMLImageElement.attributionSrcContexte sécuriséExpérimental: Permet d'obtenir ou de définir l'attribut attributionsrc sur un élément<img> de façon programmatique, reflétant la valeur de cet attribut.attributionsrc indique que le navigateur doit envoyer un en-têteAttribution-Reporting-Eligible avec la requête d'image. Côté serveur, cela sert à déclencher l'envoi d'un en-têteAttribution-Reporting-Register-Source ouAttribution-Reporting-Register-Trigger dans la réponse, afin d'enregistrer unesource d'attribution ou undéclencheur d'attribution.
HTMLImageElement.completeLecture seule: Retourne une valeur booléenne àtrue si le navigateur a fini de récupérer l'image, que ce soit avec succès ou non. Cela vaut aussitrue si l'image n'a pas de valeursrc indiquant une image à charger.
HTMLImageElement.crossOrigin: Une chaîne de caractères indiquant le paramétrage CORS pour cet élément image. Voirles attributs de paramétrage du CORS pour plus de détails. Peut valoirnull si CORS n'est pas utilisé.
HTMLImageElement.currentSrcLecture seule: Retourne une chaîne de caractères représentant l'URL depuis laquelle l'image actuellement affichée a été chargée. Cette valeur peut changer si l'image est modifiée en fonction des conditions, par exemple via desrequêtes média.
HTMLImageElement.decoding: Une chaîne de caractères optionnelle indiquant une préférence sur la façon dont le navigateur doit décoder l'image. Les valeurs possibles sont :sync (décodage synchrone),async (décodage asynchrone), ouauto (pas de préférence, valeur par défaut). Voir la pagedecoding pour plus de détails.
HTMLImageElement.fetchPriority: Une chaîne de caractères optionnelle indiquant une préférence sur la priorité de récupération de l'image par rapport aux autres images. Les valeurs possibles sont :high (priorité haute),low (priorité basse), ouauto (pas de préférence, valeur par défaut).
HTMLImageElement.height: Un entier qui reflète l'attribut HTMLheight, indiquant la hauteur affichée de l'image en pixels CSS.
HTMLImageElement.isMap: Un booléen qui reflète l'attribut HTMLismap, indiquant que l'image fait partie d'une carte côté serveur. Différent d'une carte côté client, qui utilise un élément<img> et un<map> contenant des<area> pour les zones cliquables. L'imagedoit être contenue dans un élément<a> ; voir la pageismap pour plus de détails.
HTMLImageElement.loading: Une chaîne de caractères fournissant une indication au navigateur pour optimiser le chargement du document, en déterminant s'il faut charger l'image immédiatement (eager) ou à la demande (lazy).
HTMLImageElement.naturalHeightLecture seule: Retourne un entier représentant la hauteur intrinsèque de l'image en pixels CSS, si disponible ; sinon, retourne0. C'est la hauteur que l'image aurait si elle était affichée à sa taille naturelle.
HTMLImageElement.naturalWidthLecture seule: Un entier représentant la largeur intrinsèque de l'image en pixels CSS, si disponible ; sinon, retourne0. C'est la largeur que l'image aurait si elle était affichée à sa taille naturelle.
HTMLImageElement.referrerPolicy: Une chaîne de caractères qui reflète l'attribut HTMLreferrerpolicy, indiquant à l'user agent quelle politique de référent utiliser pour récupérer l'image. Voir l'article pour les valeurs possibles.
HTMLImageElement.sizes: Une chaîne de caractères reflétant l'attribut HTMLsizes. Cette chaîne spécifie une liste de tailles conditionnelles séparées par des virgules pour l'image ; c'est-à-dire, pour une taille de zone d'affichage donnée, une taille d'image particulière sera utilisée. Voir la documentation desizes pour le format de cette chaîne.
HTMLImageElement.src: Une chaîne de caractères qui reflète l'attribut HTMLsrc, contenant l'URL complète de l'image (y compris la base). Vous pouvez charger une autre image en modifiant l'URL dans l'attributsrc.
HTMLImageElement.srcset: Une chaîne de caractères reflétant l'attribut HTMLsrcset. Cela spécifie une liste d'images candidates, séparées par des virgules. Chaque image candidate est une URL suivie d'un espace, puis d'une chaîne indiquant la taille de l'image (largeur ou multiple de taille). Voir la pagesrcset pour le format détaillé.
HTMLImageElement.useMap: Une chaîne de caractères reflétant l'attribut HTMLusemap, contenant l'URL locale de la page du<map> décrivant la carte d'image à utiliser. L'URL locale commence par# suivi de l'ID de l'élément<map>, par exemple#ma-carte. Le<map> contient à son tour des<area> pour les zones cliquables.
HTMLImageElement.width: Un entier qui reflète l'attribut HTMLwidth, indiquant la largeur affichée de l'image en pixels CSS.
HTMLImageElement.xLecture seule: Un entier indiquant le décalage horizontal du bord gauche de la boîte de mise en page CSS de l'image par rapport à l'origine du bloc contenant<html>.
HTMLImageElement.yLecture seule: Un entier indiquant le décalage vertical du bord supérieur de la boîte de mise en page CSS de l'image par rapport à l'origine du bloc contenant<html>.

Propriétés obsolètes

HTMLImageElement.alignObsolète: Une chaîne de caractères indiquant l'alignement de l'image par rapport au contexte environnant. Les valeurs possibles sont "left", "right", "justify" et "center". Obsolète : utilisez plutôt le CSS (par exemple text-align, qui fonctionne aussi pour les images) pour définir l'alignement.
HTMLImageElement.borderObsolète: Une chaîne de caractères définissant la largeur de la bordure entourant l'image. Obsolète : utilisez la propriété CSS border à la place.
HTMLImageElement.hspaceObsolète: Un entier indiquant l'espace (en pixels) à laisser vide à gauche et à droite de l'image.
HTMLImageElement.longDescObsolète: Une chaîne de caractères spécifiant l'URL où trouver une description longue du contenu de l'image. Cela servait à transformer l'image en lien automatiquement. En HTML moderne, placez plutôt un<img> dans un élément <a> définissant le lien.
HTMLImageElement.nameObsolète: Une chaîne de caractères représentant le nom de l'élément.
HTMLImageElement.vspaceObsolète: Un entier indiquant l'espace vide (en pixels) à laisser au-dessus et en dessous de l'image.

Méthodes d'instance

Hérite des méthodes de son parent,HTMLElement.

HTMLImageElement.decode(): Retourne une promesse (Promise) qui se résout lorsque l'image est décodée et qu'il est sûr de l'ajouter au DOM. Cela évite que le rendu de l'image ne bloque la prochaine frame si une image non décodée était ajoutée au DOM.

Si une erreur se produit lors du chargement ou du rendu de l'image, et qu'un gestionnaire d'évènementonerror a été configuré pour l'évènementerror, ce gestionnaire sera appelé. Cela peut arriver dans plusieurs situations :

L'attributsrc est vide ounull.
L'URLsrc indiquée est la même que celle de la page courante.
L'image indiquée est corrompue et ne peut pas être chargée.
Les métadonnées de l'image sont corrompues de telle sorte qu'il est impossible d'en récupérer les dimensions, et aucune dimension n'a été spécifiée dans les attributs de l'élément<img>.
L'image indiquée est dans un format non pris en charge par l'agent utilisateur.

Exemple

const img1 = new Image(); // Constructeur Imageimg1.src = "image1.png";img1.alt = "texte alternatif";document.body.appendChild(img1);const img2 = document.createElement("img"); // Utilisation de HTMLImageElement via le DOMimg2.src = "image2.jpg";img2.alt = "autre texte alternatif";document.body.appendChild(img2);// Utiliser la première image du documentalert(document.images[0].src);