HTMLImageElement

Constructeur

Image()

Le constructeur Image() crée et retourne un nouvel objet HTMLImageElement 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 HTML alt, indiquant le contenu de remplacement à afficher si l'image n'a pas été chargée.

HTMLImageElement.attributionSrc Contexte 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ête Attribution-Reporting-Eligible avec la requête d'image. Côté serveur, cela sert à déclencher l'envoi d'un en-tête Attribution-Reporting-Register-Source ou Attribution-Reporting-Register-Trigger dans la réponse, afin d'enregistrer une source d'attribution ou un déclencheur d'attribution.

HTMLImageElement.complete Lecture 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 aussi true si l'image n'a pas de valeur src indiquant une image à charger.

HTMLImageElement.crossOrigin

Une chaîne de caractères indiquant le paramétrage CORS pour cet élément image. Voir les attributs de paramétrage du CORS pour plus de détails. Peut valoir null si CORS n'est pas utilisé.

HTMLImageElement.currentSrc Lecture 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 des requê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), ou auto (pas de préférence, valeur par défaut). Voir la page decoding 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), ou auto (pas de préférence, valeur par défaut).

HTMLImageElement.height

Un entier qui reflète l'attribut HTML height, indiquant la hauteur affichée de l'image en pixels CSS.

HTMLImageElement.isMap

Un booléen qui reflète l'attribut HTML ismap, 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'image doit être contenue dans un élément <a> ; voir la page ismap 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.naturalHeight Lecture seule

Retourne un entier représentant la hauteur intrinsèque de l'image en pixels CSS, si disponible ; sinon, retourne 0. C'est la hauteur que l'image aurait si elle était affichée à sa taille naturelle.

HTMLImageElement.naturalWidth Lecture seule

Un entier représentant la largeur intrinsèque de l'image en pixels CSS, si disponible ; sinon, retourne 0. 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 HTML referrerpolicy, 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 HTML sizes. 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 de sizes pour le format de cette chaîne.

HTMLImageElement.src

Une chaîne de caractères qui reflète l'attribut HTML src, contenant l'URL complète de l'image (y compris la base). Vous pouvez charger une autre image en modifiant l'URL dans l'attribut src.

HTMLImageElement.srcset

Une chaîne de caractères reflétant l'attribut HTML srcset. 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 page srcset pour le format détaillé.

HTMLImageElement.useMap

Une chaîne de caractères reflétant l'attribut HTML usemap, 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 HTML width, indiquant la largeur affichée de l'image en pixels CSS.

HTMLImageElement.x Lecture 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.y Lecture 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.align Obsolè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.border Obsolè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.hspace Obsolète

Un entier indiquant l'espace (en pixels) à laisser vide à gauche et à droite de l'image.

HTMLImageElement.longDesc Obsolè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.name Obsolète

Une chaîne de caractères représentant le nom de l'élément.

HTMLImageElement.vspace Obsolè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.

Erreurs

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

• L'attribut src est vide ou null.
• L'URL src 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 Image
img1.src = "image1.png";
img1.alt = "texte alternatif";
document.body.appendChild(img1);

const img2 = document.createElement("img"); // Utilisation de HTMLImageElement via le DOM
img2.src = "image2.jpg";
img2.alt = "autre texte alternatif";
document.body.appendChild(img2);

// Utiliser la première image du document
alert(document.images[0].src);

Spécifications

Compatibilité des navigateurs

Voir aussi

• Élément HTML implémentant cette interface : <img>