Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

HTMLImageElement: caricamento delle immagini, dimensioni e stato complete

HTMLImageElement consente di impostare la sorgente e il testo alternativo di un’immagine, gestire gli eventi load ed error e leggere le dimensioni naturali. La proprietà complete non dimostra che il caricamento sia riuscito: è true anche per un’immagine non valida o un elemento senza sorgente.

Versione: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintassi

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.complete

HTMLImageElement rappresenta un elemento immagine; new Image() ne crea uno senza aggiungerlo al documento. HTMLImageElement.src imposta l’URL della risorsa e HTMLImageElement.alt il testo alternativo. Fornisci una descrizione significativa per un’immagine informativa; usa un alt vuoto per un’immagine decorativa.

HTMLImageElement.load e HTMLImageElement.error indicano qui gli eventi load ed error, non metodi da chiamare. Il primo segnala il caricamento riuscito, il secondo un errore di caricamento o rendering. Registra entrambi i listener con addEventListener prima di assegnare src, così un caricamento rapido non termina prima della registrazione.

Le proprietà di sola lettura HTMLImageElement.naturalWidth e HTMLImageElement.naturalHeight indicano le dimensioni intrinseche corrette per la densità, in pixel CSS, non la dimensione imposta dagli stili. Una dimensione non disponibile vale 0. HTMLImageElement.complete è di sola lettura: può essere true dopo un successo, dopo un errore, in assenza di una sorgente o con src vuoto. complete da solo, quindi, non dimostra il successo.

Per un elemento già esistente, registra prima entrambi i listener, poi controlla lo stato attuale. Se l’elemento non ha una sorgente, gestisci il caso separatamente, ma ricorda che un elemento picture che lo contiene può fornire una sorgente. Se l’elemento ha una sorgente e complete vale false, attendi load o error. La condizione complete && naturalWidth > 0 non dimostra che il caricamento sia riuscito. Per un img privo di attributi src e srcset, complete può valere true mentre l’immagine fornita dal picture che lo contiene è ancora in fase di caricamento. naturalWidth può assumere un valore positivo non appena le dimensioni sono disponibili, prima che il caricamento termini. Se complete && naturalWidth === 0, queste proprietà non consentono comunque di stabilire l’esito: anche un’immagine senza larghezza intrinseca può essere caricata correttamente. Non considerarla indisponibile su questa base. Se hai già rilevato un evento load o error per la richiesta corrente dell’immagine, usa quel risultato. Un listener appena registrato non riceve un evento già generato. Evita che il controllo dello stato e i listener elaborino due volte lo stesso risultato.

Questa è un’API del browser definita da HTML, non una funzionalità di una particolare edizione di ECMAScript. I meccanismi di base descritti sono ampiamente supportati; la presenza di Node 24 in un repository non dimostra la disponibilità di un’API del browser. L’esempio crea in memoria un’immagine SVG decorativa senza aggiungerla al documento. L’SVG ha una larghezza e un’altezza positive definite esplicitamente, quindi l’esempio non mostra un caricamento riuscito in assenza di una larghezza intrinseca.

Esempi

(() => {
  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)}`;
})();

Risultato

load: 2x3; complete=true

Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.

Fonti