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

CKTIS / JavaScript

Dimensions naturelles d’une image et état `complete`

Lisez les dimensions naturelles d’une image en pixels CSS et distinguez la fin d’une requête d’un chargement ou d’un décodage réussi.

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

Syntaxe

img.naturalWidth  // number: natural width
img.naturalHeight // number: natural height
img.complete      // boolean: completion state, not success

naturalWidth et naturalHeight sont des propriétés en lecture seule de HTMLImageElement. Elles donnent la largeur et la hauteur naturelles de l’image courante sous forme d’entiers en pixels CSS. Elles tiennent compte de la densité de pixels de la ressource sélectionnée et de l’orientation inscrite dans les métadonnées : elles peuvent donc différer des dimensions enregistrées dans le fichier. Pour un élément effectivement rendu, width et height décrivent plutôt sa taille sur la page.

Tant que les dimensions de l’image courante ne sont pas disponibles, les deux propriétés renvoient 0. Les dimensions peuvent être connues avant la fin du téléchargement : des valeurs positives ne prouvent donc pas que l’image entière a été chargée ou décodée. Vérifiez que les deux dimensions sont positives avant de calculer img.naturalWidth / img.naturalHeight.

complete est une propriété booléenne en lecture seule. Elle vaut true si src et srcset sont absents, ou si src est vide et srcset absent. Elle vaut aussi true si l’image de la requête courante est entièrement disponible ou si cette requête a échoué, à condition qu’aucune requête de remplacement ne soit en attente. Sinon, elle vaut false. C’est un état à l’instant de la lecture, pas une preuve de réussite.

Installez les gestionnaires load et error avant de définir src pour distinguer la réussite de l’échec. Si vous avez besoin de l’image décodée, utilisez await img.decode() après avoir défini la source et gérez le rejet de la promesse. Ces API Web appartiennent à la plateforme du navigateur, pas au cœur d’ECMAScript.

Exemples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Natural image dimensions and completion</title>
</head>
<body>
<script>
(async () => {
  function report(label, img) {
    console.log(`${label}: ${img.complete} ${img.naturalWidth} ${img.naturalHeight}`);
  }

  async function inspect(src) {
    const img = new Image();
    const eventType = await new Promise((resolve) => {
      img.onload = img.onerror = (event) => resolve(event.type);
      img.src = src;
    });
    report(eventType, img);
  }

  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="16"><rect width="24" height="16"/></svg>';
  report('no source', new Image());
  await inspect('data:image/svg+xml,' + encodeURIComponent(svg));
  await inspect('data:image/svg+xml,not-an-svg');
})();
</script>
</body>
</html>

Résultat

no source: true 0 0
load: true 24 16
error: true 0 0

Les trois lignes montrent une image sans source, un SVG valide de 24 × 16 et un SVG invalide. `complete` vaut `true` dans les trois cas. Ouvrez le fichier HTML dans un navigateur où le chargement des images est activé et où les images `data:` sont autorisées, puis consultez la console de développement.

Leçons associées

  • JavaScript · Leçon 33 · Avancé · Version : 4

Sources