CKTIS / JavaScript
HTMLImageElement : chargement d’image, dimensions et état complete
HTMLImageElement permet de définir la source et le texte alternatif d’une image, de gérer les événements load et error, et de lire ses dimensions naturelles. La propriété complete ne prouve pas la réussite : elle vaut aussi true pour une image défectueuse ou un élément sans source.
Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntaxe
const image = new Image();
image.alt = description;
image.addEventListener("load", onLoad, { once: true });
image.addEventListener("error", onError, { once: true });
image.src = url;
// Read: image.naturalWidth, image.naturalHeight, image.completeHTMLImageElement représente un élément image ; new Image() en crée un sans l’ajouter au document. HTMLImageElement.src définit l’URL de la ressource et HTMLImageElement.alt le texte alternatif. Fournissez une description pertinente pour une image informative ; utilisez un alt vide pour une image décorative.
HTMLImageElement.load et HTMLImageElement.error désignent ici les événements load et error, et non des méthodes à appeler. Le premier signale un chargement réussi, le second un échec de chargement ou de rendu. Enregistrez les deux écouteurs avec addEventListener avant d’attribuer src, afin qu’un chargement rapide ne se termine pas avant leur enregistrement.
Les propriétés en lecture seule HTMLImageElement.naturalWidth et HTMLImageElement.naturalHeight indiquent les dimensions intrinsèques corrigées selon la densité, en pixels CSS, et non la taille imposée par les styles. Une dimension indisponible vaut 0. HTMLImageElement.complete est en lecture seule : sa valeur peut être true après une réussite, un échec, en l’absence de source ou avec un src vide. complete seul ne prouve donc pas la réussite.
Pour un élément existant, enregistrez d’abord les deux écouteurs, puis vérifiez l’état actuel de l’élément. Si l’élément n’a pas de source, traitez ce cas séparément, mais gardez à l’esprit qu’un élément picture englobant peut fournir une source. Si l’élément a une source et que complete vaut false, attendez load ou error. La condition complete && naturalWidth > 0 ne prouve pas que le chargement a réussi. Pour un img dépourvu d’attributs src et srcset, complete peut valoir true alors que l’image fournie par le picture englobant est encore en cours de chargement. naturalWidth peut prendre une valeur positive dès que les dimensions sont disponibles, avant la fin du chargement. Si complete && naturalWidth === 0, ces propriétés ne permettent pas non plus de connaître le résultat : une image sans largeur intrinsèque peut se charger correctement. Ne la considérez pas comme indisponible sur cette seule base. Si vous avez déjà relevé un événement load ou error pour la requête d’image en cours, utilisez ce résultat. Un écouteur nouvellement enregistré ne recevra pas un événement déjà déclenché. Veillez à ce que la vérification de l’état et les écouteurs ne traitent pas deux fois le même résultat.
Il s’agit d’une API de navigateur définie par HTML, et non d’une fonctionnalité d’une édition particulière d’ECMAScript. Les mécanismes de base décrits sont largement pris en charge ; la présence de Node 24 dans un dépôt ne prouve pas la disponibilité d’une API de navigateur. L’exemple crée en mémoire une image SVG décorative sans l’ajouter au document. La largeur et la hauteur du SVG sont explicitement définies et positives : l’exemple ne montre donc pas le chargement réussi d’une image sans largeur intrinsèque.
Exemples
(() => {
const image = new Image();
image.alt = "";
image.addEventListener("load", () => {
console.log(`load: ${image.naturalWidth}x${image.naturalHeight}; complete=${image.complete}`);
}, { once: true });
image.addEventListener("error", () => {
console.log("error: image unavailable");
}, { once: true });
const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="2" height="3"><rect width="2" height="3" fill="blue"/></svg>';
image.src = `data:image/svg+xml,${encodeURIComponent(svg)}`;
})();Résultat
load: 2x3; complete=true
Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.