Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Dimensiones naturales de una imagen y estado `complete`

Consulta el tamaño natural de una imagen en píxeles CSS y distingue el fin de una solicitud de una carga o decodificación correcta.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

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

naturalWidth y naturalHeight son propiedades de solo lectura de HTMLImageElement. Devuelven la anchura y la altura naturales de la imagen actual como enteros en píxeles CSS. Tienen en cuenta la densidad de píxeles del recurso seleccionado y la orientación indicada en los metadatos, por lo que pueden diferir de las dimensiones almacenadas en el archivo. En un elemento que se está renderizando, width y height describen en cambio su tamaño en la página.

Si las dimensiones de la imagen actual aún no están disponibles, ambas propiedades devuelven 0. Las dimensiones pueden conocerse antes de que termine la descarga, así que unos valores positivos no demuestran que se haya cargado o decodificado toda la imagen. Comprueba que ambas dimensiones sean positivas antes de calcular img.naturalWidth / img.naturalHeight.

complete es una propiedad booleana de solo lectura. Vale true si no hay src ni srcset, o si src está vacío y no hay srcset. También vale true si la imagen de la solicitud actual está completamente disponible o si la solicitud ha fallado, siempre que no haya una solicitud de reemplazo pendiente. En los demás casos vale false. Refleja el estado en el momento de la lectura, no el éxito de la carga.

Registra los manejadores de load y error antes de asignar src para distinguir el éxito del fallo. Si necesitas la imagen decodificada, usa await img.decode() tras asignar la fuente y gestiona el rechazo de la promesa. Son API web del navegador, no funciones del núcleo de ECMAScript.

Ejemplos

<!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>

Resultado

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

Las tres líneas muestran una imagen sin fuente, un SVG válido de 24 × 16 y un SVG no válido. En los tres casos `complete` vale `true`. Abre el archivo HTML en un navegador que permita imágenes `data:` y tenga activada la carga de imágenes; luego consulta la consola de desarrollo.

Lecciones relacionadas

  • JavaScript · Lección 33 · Avanzado · Versión: 4

Fuentes