KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / JavaScript

HTMLImageElement: afbeeldingen laden, afmetingen en de status complete

Met HTMLImageElement kun je de afbeeldingsbron en alternatieve tekst instellen, de gebeurtenissen load en error afhandelen en de natuurlijke afmetingen uitlezen. De eigenschap complete bewijst geen succes: deze is ook true bij een beschadigde afbeelding of een element zonder bron.

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

Syntax

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 staat voor een afbeeldingselement; new Image() maakt er een zonder het aan het document toe te voegen. HTMLImageElement.src stelt de URL van de bron in en HTMLImageElement.alt de alternatieve tekst. Geef een betekenisvolle beschrijving voor een informatieve afbeelding; gebruik een lege alt voor een decoratieve afbeelding.

HTMLImageElement.load en HTMLImageElement.error verwijzen hier naar de gebeurtenissen load en error, niet naar aanroepbare methoden. De eerste meldt dat het laden is gelukt, de tweede een laad- of weergavefout. Registreer beide luisteraars met addEventListener voordat je src instelt, zodat een snelle laadactie niet al klaar is voordat de registratie plaatsvindt.

De alleen-lezen eigenschappen HTMLImageElement.naturalWidth en HTMLImageElement.naturalHeight geven de voor pixeldichtheid gecorrigeerde intrinsieke afmetingen in CSS-pixels, niet de door stijlen opgelegde grootte. Een niet-beschikbare afmeting is 0. HTMLImageElement.complete is alleen-lezen: de waarde kan true zijn na succes, na een fout, zonder bron of met een lege src. complete alleen bewijst dus geen succes.

Registreer bij een bestaand element eerst beide luisteraars en controleer daarna de huidige status. Heeft het element geen bron, handel dat geval dan apart af. Houd er wel rekening mee dat een omringend picture-element een bron kan leveren. Heeft het element een bron en is complete gelijk aan false, wacht dan op load of error. De voorwaarde complete && naturalWidth > 0 bewijst niet dat het laden is gelukt. Bij een img zonder eigen src- of srcset-attribuut kan complete de waarde true hebben terwijl de afbeelding uit het omringende picture-element nog wordt geladen. naturalWidth kan al positief worden zodra de afmetingen bekend zijn, nog voordat het laden klaar is. Als complete && naturalWidth === 0 geldt, kun je evenmin uit deze eigenschappen afleiden of het laden is gelukt: ook een afbeelding zonder intrinsieke breedte kan correct worden geladen. Beschouw de afbeelding op grond hiervan niet als onbeschikbaar. Heb je voor het huidige afbeeldingsverzoek al een load- of error-gebeurtenis vastgelegd, gebruik dan die uitkomst. Een pas geregistreerde luisteraar ontvangt geen gebeurtenis die al is afgevuurd. Zorg dat de statuscontrole en de luisteraars hetzelfde resultaat niet twee keer afhandelen.

Dit is een browser-API die door HTML is gedefinieerd, geen functie van een bepaalde ECMAScript-editie. De beschreven basismechanismen worden breed ondersteund; de aanwezigheid van Node 24 in een repository bewijst niet dat een browser-API beschikbaar is. Het voorbeeld maakt een decoratieve SVG-afbeelding in het geheugen zonder die aan het document toe te voegen. Voor de SVG zijn een positieve breedte en hoogte expliciet ingesteld; het voorbeeld laat dus niet zien dat een afbeelding zonder intrinsieke breedte succesvol kan worden geladen.

Voorbeelden

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

Resultaat

load: 2x3; complete=true

De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.

Bronnen