SVGImageElement.decoding — Eigenschaft · JavaScript-Referenz

Signatur

SVGImageElement.decoding

Beschreibung

Die Eigenschaft decoding des SVGImageElement spiegelt das Attribut decoding eines SVG-<image>-Elements wider. Mit ihr kann man dem Browser mitteilen, ob das Decodieren der Bilddaten den Rendervorgang blockieren darf ("sync"), ob es im Hintergrund laufen soll ("async") oder ob der Browser selbst entscheidet ("auto", Standard).

Das ist vor allem bei großen Rastergrafiken in SVG-Grafiken nützlich, etwa bei Karten, Diagrammen mit Hintergrundfotos oder interaktiven Infografiken. Mit "async" kann der übrige SVG-Inhalt schon gezeichnet werden, während das Bild noch decodiert wird. So bleibt die Seite reaktionsfähig. Mit "sync" erscheint das Bild dagegen zusammen mit dem restlichen Inhalt, ohne kurz „nachzuflackern“.

Der Wert ist nur ein Hinweis. Der Browser muss ihn nicht befolgen. Wer wirklich sicher wissen will, wann ein Bild fertig decodiert ist, sollte zusätzlich SVGImageElement.prototype.decode() verwenden. Diese Methode gibt ein Promise zurück, das sich erfüllt, sobald das Bild bereit zum Zeichnen ist.

Parameter

Name	Typ	Default	Beschreibung
$value	"sync" \| "async" \| "auto"	"auto"	Beim Setzen: `"sync"` decodiert synchron zusammen mit dem übrigen Inhalt, `"async"` decodiert asynchron, `"auto"` überlässt die Wahl dem Browser. Ungültige Werte werden beim Lesen als `"auto"` zurückgegeben.

Rückgabewert

Typ

string

Beschreibung

Einer der Werte "sync", "async" oder "auto". Fehlt das Attribut oder ist es ungültig, wird "auto" zurückgegeben.

Beispiele

Wert lesen und auf asynchron setzen

const img = document.querySelector('svg image');
console.log(img.decoding); // Standardwert

img.decoding = 'async';
console.log(img.decoding);
console.log(img.getAttribute('decoding'));

auto async async

Großes Hintergrundbild dynamisch und nicht blockierend einfügen

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.querySelector('#karte');

const bild = document.createElementNS(SVG_NS, 'image');
bild.decoding = 'async'; // Decodierung soll das Rendering nicht blockieren
bild.setAttribute('href', '/img/satellit-4k.jpg');
bild.setAttribute('width', '800');
bild.setAttribute('height', '600');

svg.prepend(bild);

Bildwechsel ohne Flackern mit decode()

const wechsleBild = async (imageEl, url) => {
  const SVG_NS = 'http://www.w3.org/2000/svg';
  const neu = document.createElementNS(SVG_NS, 'image');
  neu.decoding = 'sync';
  neu.setAttribute('href', url);
  neu.setAttribute('width', imageEl.getAttribute('width'));
  neu.setAttribute('height', imageEl.getAttribute('height'));

  try {
    await neu.decode(); // wartet, bis das Bild decodiert ist
    imageEl.replaceWith(neu);
    console.log('Bild ausgetauscht');
  } catch (err) {
    console.error('Decodierung fehlgeschlagen:', err);
  }
};

wechsleBild(document.querySelector('#vorschau'), '/img/detail.png');

Bild ausgetauscht

Unterstützung prüfen

const unterstuetzt = 'decoding' in SVGImageElement.prototype;
console.log(unterstuetzt ? 'decoding verfügbar' : 'nicht unterstützt');

decoding verfügbar

// Wichtig · Fallstricke

Nur ein Hinweis: Browser können den Wert ignorieren. Für zuverlässiges Timing solltest du decode() oder das load-Event verwenden.
Ungültige Werte: Das Setzen eines unbekannten Strings (z. B. "fast") wirft keinen Fehler. Der Wert landet im Attribut, beim Lesen erscheint aber \"auto\".
Kompatibilität: Wird in allen modernen Browsern unterstützt, nicht aber im Internet Explorer. Ältere Safari-Versionen unterstützen decoding nur bei HTML-<img>, nicht bei SVG-<image>. Deshalb vorher per Feature-Erkennung prüfen.
Setzzeitpunkt: Setze decoding am besten vor href. Sonst hat der Browser mit dem Laden und Decodieren womöglich schon begonnen.
"sync" kann bei sehr großen Bildern den Hauptthread spürbar blockieren und das Rendering verzögern.

Siehe auch

SVGImageElement SVGImageElement.decode() HTMLImageElement.decoding HTMLImageElement.decode() Document.createElementNS() HTMLTableElement.bgColor PerformanceTiming.domComplete