CKTIS / JavaScript
HTMLImageElement: carga de imágenes, dimensiones y estado complete
HTMLImageElement permite establecer la fuente y el texto alternativo de una imagen, gestionar los eventos load y error y consultar sus dimensiones naturales. La propiedad complete no demuestra que la carga haya tenido éxito: también es true para una imagen dañada o un elemento sin fuente.
Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxis
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 representa un elemento de imagen; new Image() crea uno sin añadirlo al documento. HTMLImageElement.src establece la URL del recurso y HTMLImageElement.alt, el texto alternativo. Proporciona una descripción significativa para una imagen informativa; usa un alt vacío para una imagen decorativa.
HTMLImageElement.load y HTMLImageElement.error se refieren aquí a los eventos load y error, no a métodos que se puedan llamar. El primero indica que la carga se ha completado correctamente; el segundo, un fallo de carga o de representación. Registra ambos escuchadores con addEventListener antes de asignar src, para que una carga rápida no termine antes de registrarlos.
Las propiedades de solo lectura HTMLImageElement.naturalWidth y HTMLImageElement.naturalHeight indican las dimensiones intrínsecas corregidas por densidad, en píxeles CSS, no el tamaño impuesto por los estilos. Una dimensión no disponible vale 0. HTMLImageElement.complete es de solo lectura: puede ser true tras una carga correcta o fallida, sin fuente o con un src vacío. Por tanto, complete por sí solo no demuestra que haya habido éxito.
Para un elemento existente, registra primero ambos escuchadores y luego comprueba el estado actual. Si el elemento no tiene fuente, trata ese caso por separado, pero recuerda que un elemento picture que lo contiene puede proporcionar una fuente. Si el elemento tiene una fuente y complete es false, espera a load o error. La condición complete && naturalWidth > 0 no demuestra que la carga haya tenido éxito. En un img que no tiene atributos propios src ni srcset, complete puede valer true mientras todavía se está cargando la imagen proporcionada por el picture que lo contiene. naturalWidth puede tomar un valor positivo en cuanto estén disponibles las dimensiones, antes de que termine la carga. Si complete && naturalWidth === 0, estas propiedades tampoco permiten determinar el resultado: una imagen sin anchura intrínseca puede cargarse correctamente. No la des por no disponible basándote en esa condición. Si has registrado un evento load o error para la solicitud actual de la imagen, utiliza ese resultado. Un escuchador recién registrado no recibirá un evento que ya se haya disparado. Evita que la comprobación del estado y los escuchadores procesen dos veces el mismo resultado.
Esta es una API del navegador definida por HTML, no una característica de una edición concreta de ECMAScript. Los mecanismos básicos descritos tienen amplia compatibilidad; la presencia de Node 24 en un repositorio no demuestra que una API del navegador esté disponible. El ejemplo crea en memoria una imagen SVG decorativa sin añadirla al documento. El SVG tiene una anchura y una altura positivas definidas explícitamente, por lo que el ejemplo no muestra una carga correcta sin anchura intrínseca.
Ejemplos
(() => {
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)}`;
})();Resultado
load: 2x3; complete=true
El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.