HTMLImageElement: `decode()` Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Die decode()-Methode des HTMLImageElement-Interfaces gibt ein Promise zurück, das aufgelöst wird, sobald das Bild decodiert ist und es sicher ist, es dem DOM hinzuzufügen.

Dies kann verwendet werden, um das Laden des Bildes vor der Einbindung in ein Element im DOM (oder dem Hinzufügen zum DOM als neues Element) zu starten, sodass das Bild sofort gerendert werden kann, wenn es dem DOM hinzugefügt wird. Dies verhindert Verzögerungen beim Rendern des nächsten Frames, nachdem das Bild dem DOM hinzugefügt wurde, während das Bild geladen wird.

Syntax

js
decode()

Parameter

Keine.

Rückgabewert

Ein Promise das mit undefined erfüllt wird, sobald die Bilddaten zur Verwendung bereit sind.

Ausnahmen

EncodingError

Ein DOMException, der anzeigt, dass ein Fehler beim Decodieren des Bildes aufgetreten ist.

Anwendungshinweise

Ein potenzieller Anwendungsfall für decode(): Beim Laden sehr großer Bilder (zum Beispiel in einem Online-Fotoalbum) kann zunächst ein niedrig aufgelöstes Thumbnail-Bild angezeigt und dann dieses Bild durch das voll aufgelöste Bild ersetzt werden. Hierzu wird ein neues HTMLImageElement instanziiert, dessen Quelle auf die URL des voll aufgelösten Bildes gesetzt und anschließend decode() verwendet, um ein Promise zu erhalten, das aufgelöst wird, sobald das voll aufgelöste Bild zur Verfügung steht. Zu diesem Zeitpunkt kann das niedrig aufgelöste Bild durch das nun verfügbare voll aufgelöste Bild ersetzt werden.

Beispiele

Grundlegende Verwendung

Das folgende Beispiel zeigt, wie die decode()-Methode verwendet wird, um zu steuern, wann ein Bild dem DOM hinzugefügt wird.

js
const img = new Image();
img.src = "nebula.jpg";
img
  .decode()
  .then(() => {
    document.body.appendChild(img);
  })
  .catch((encodingError) => {
    // Do something with the error.
  });

Hinweis: Ohne eine Methode, die ein Promise zurückgibt, würden Sie das Bild in einem load-Ereignishandler dem DOM hinzufügen und den Fehler im error-Ereignishandler behandeln.

Vermeidung leerer Bilder

Im folgenden Beispiel wird wahrscheinlich ein leeres Bild auf der Seite angezeigt, da das Bild heruntergeladen wird:

js
const img = new Image();
img.src = "img/logo.png";
document.body.appendChild(img);

Die Verwendung von decode() verzögert das Einfügen des Bildes in das DOM, bis es vollständig heruntergeladen und decodiert ist, wodurch das Problem des leeren Bildes vermieden wird:

js
async function getImage() {
  const img = new Image();
  img.src = "img/logo.png";
  await img.decode();
  document.body.appendChild(img);
  const p = document.createElement("p");
  p.textContent = "Image is fully loaded!";
  document.body.appendChild(p);
}

Dies ist besonders nützlich, wenn Sie ein bestehendes Bild dynamisch durch ein neues ersetzen, und verhindert außerdem, dass nicht verwandte Darstellungen außerhalb dieses Codes blockiert werden, während das Bild decodiert wird.

Spezifikationen

Specification
HTML Standard
# dom-img-decode-dev

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch