WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Bildereignisse `load` und `error`

Behandle Erfolg und Fehlschlag beim Laden direkt am Bildelement. Registriere beide Handler vor dem Setzen von `src` und werte `complete` nicht als Erfolgsnachweis.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

const image = new Image();
image.addEventListener("load", onLoad);
image.addEventListener("error", onError);
image.src = url;

// Alternative to addEventListener():
// image.onload = onLoad;
// image.onerror = onError;

new Image() erzeugt ein HTMLImageElement, also ein <img>, das ein Bild auch ohne Einfügen in das Dokument laden kann. Das ist eine Browser-API und kein Bestandteil von ECMAScript 2024. Der Browser löst am Element load aus, wenn die Ressource erfolgreich geladen wurde, und error, wenn er sie nicht laden oder verwenden kann, etwa bei einer unerreichbaren URL oder ungültigen Bilddaten. Das Bildereignis error ist weder eine ausgelöste JavaScript-Ausnahme noch eine Antwort mit HTTP-Statuscode.

Registriere die Handler direkt am Bild: Keines der Ereignisse durchläuft die Bubbling-Phase, und keines ist abbrechbar. Rufe für beide addEventListener() auf, bevor du src zuweist. Alternativ kannst du onload und onerror setzen; eine erneute Zuweisung ersetzt den Handler in der jeweiligen Eigenschaft. Beim Lesen von src erhältst du eine URL, weder das Ladeergebnis noch ein Promise.

Hat ein vorhandenes Bild ein Ereignis bereits ausgelöst, wird es für einen neuen Listener nicht wiederholt. complete allein belegt keinen Erfolg: Auch bei einem defekten Bild oder einer fehlenden Quelle kann der Wert true sein. Bei einem erwarteten Bild mit positiver intrinsischer Breite kannst du mit image.complete && image.naturalWidth > 0 prüfen, ob es bereits verfügbar ist.

load bedeutet nicht, dass das Bild schon gezeichnet wurde. Soll das Bild vor dem Einfügen ins Dokument dekodiert sein, verwende await image.decode() und behandle die Ablehnung des Promise. Ein erfolgreich geladenes Bild fremder Herkunft erlaubt noch keinen lesenden Zugriff auf seine Pixel in einem canvas; die CORS-Beschränkungen gelten weiterhin.

Beispiele

<!doctype html>
<meta charset="utf-8">
<title>Image load and error events</title>
<script>
(async () => {
  function imageOutcome(url) {
    return new Promise((resolve) => {
      const image = new Image();
      function finish(event) {
        image.removeEventListener("load", finish);
        image.removeEventListener("error", finish);
        resolve(event.type);
      }
      image.addEventListener("load", finish);
      image.addEventListener("error", finish);
      image.src = url;
    });
  }

  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"><rect width="1" height="1"/></svg>';
  const dataURL = (text) => `data:image/svg+xml,${encodeURIComponent(text)}`;
  console.log(await imageOutcome(dataURL(svg)));
  console.log(await imageOutcome(dataURL("not an SVG")));
})();
</script>

Ergebnis

load
error

Speichere das Beispiel als `.html`-Datei und öffne sie in einem Browser, der auf dieser Seite `data:`-Bilder zulässt. Prüfe die Meldungen in der Browserkonsole. Ohne einen externen Server zu kontaktieren, prüft der Code erst ein gültiges SVG und dann ungültige Bilddaten. Pro Versuch verwendet er ein eigenes Bild und entfernt nach dem Ergebnis beide Listener. Erwartet werden `load` und danach `error`.

Zugehörige Lektionen

  • JavaScript · Lektion 33 · Fortgeschritten · Version: 4

Quellen