CKTIS / JavaScript
HTMLImageElement: Bildladen, Abmessungen und complete-Status
Mit HTMLImageElement lassen sich die Bildquelle und der Alternativtext festlegen, load- und error-Ereignisse behandeln und die natürlichen Abmessungen auslesen. Die Eigenschaft complete beweist keinen Erfolg: Sie ist auch bei einem fehlerhaften Bild oder einem Element ohne Quelle true.
Version: 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.completeHTMLImageElement steht für ein Bildelement; new Image() erstellt eines, ohne es in das Dokument einzufügen. HTMLImageElement.src legt die URL der Ressource fest, HTMLImageElement.alt den Alternativtext. Gib für ein inhaltlich wichtiges Bild eine aussagekräftige Beschreibung an; für ein dekoratives Bild verwendest du ein leeres alt.
HTMLImageElement.load und HTMLImageElement.error bezeichnen hier die Ereignisse load und error, keine aufrufbaren Methoden. Ersteres signalisiert erfolgreiches Laden, Letzteres einen Lade- oder Darstellungsfehler. Registriere beide Listener mit addEventListener, bevor du src zuweist, damit ein schnelles Laden nicht vor der Registrierung abgeschlossen ist.
Die schreibgeschützten Eigenschaften HTMLImageElement.naturalWidth und HTMLImageElement.naturalHeight geben die dichtekorrigierten intrinsischen Abmessungen in CSS-Pixeln an, nicht die durch Styles festgelegte Größe. Eine nicht verfügbare Abmessung hat den Wert 0. HTMLImageElement.complete ist schreibgeschützt und kann nach Erfolg, nach einem Fehler, ohne Quelle oder mit leerem src true sein. complete allein beweist also keinen Erfolg.
Registriere bei einem vorhandenen Element zuerst beide Listener und prüfe dann den aktuellen Zustand. Hat das Element keine Quelle, behandle diesen Fall gesondert. Beachte aber, dass ein umgebendes picture-Element eine Quelle bereitstellen kann. Hat das Element eine Quelle und ist complete gleich false, warte auf load oder error. Die Bedingung complete && naturalWidth > 0 beweist nicht, dass das Bild erfolgreich geladen wurde. Hat ein img weder ein eigenes src- noch ein eigenes srcset-Attribut, kann complete den Wert true haben, während das vom umgebenden picture bereitgestellte Bild noch lädt. Sobald die Abmessungen verfügbar sind, kann naturalWidth bereits vor Abschluss des Ladens positiv sein. Gilt complete && naturalWidth === 0, lässt sich das Ergebnis ebenfalls nicht aus diesen Eigenschaften ablesen: Auch ein Bild ohne intrinsische Breite kann erfolgreich geladen werden. Behandle es deshalb nicht als unverfügbar. Wenn du für die aktuelle Bildanfrage bereits ein load- oder error-Ereignis erfasst hast, verwende dieses Ergebnis. Ein neu registrierter Listener empfängt kein Ereignis, das bereits ausgelöst wurde. Stelle sicher, dass die Zustandsprüfung und die Listener nicht dasselbe Ergebnis zweimal verarbeiten.
Dies ist eine durch HTML definierte Browser-API und keine Funktion einer bestimmten ECMAScript-Ausgabe. Die beschriebenen grundlegenden Mechanismen werden breit unterstützt; Node 24 in einem Repository belegt nicht die Verfügbarkeit einer Browser-API. Das Beispiel erstellt ein dekoratives SVG-Bild im Speicher, ohne es in das Dokument einzufügen. Für das SVG sind eine positive Breite und Höhe ausdrücklich angegeben; das Beispiel zeigt daher kein erfolgreiches Laden ohne intrinsische Breite.
Beispiele
(() => {
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)}`;
})();Ergebnis
load: 2x3; complete=true
Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.