SVGImageElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGImageElement extends SVGGraphicsElement

Beschreibung

SVGImageElement ist das Interface hinter dem SVG-Element <image>. Damit bindest du externe Bilder (PNG, JPEG, WebP, GIF oder weitere SVG-Dateien) in eine SVG-Grafik ein. Das Element erbt von SVGGraphicsElement. Deshalb stehen dir auch getBBox(), getCTM() und transform zur Verfügung. Über SVGURIReference kommt außerdem die Eigenschaft href hinzu.

Die wichtigsten Eigenschaften:

x, y, width, height (SVGAnimatedLength): Position und Größe des Bildbereichs im Benutzerkoordinatensystem.
preserveAspectRatio (SVGAnimatedPreserveAspectRatio): legt fest, wie das Bild in den Bereich eingepasst wird, also Ausrichtung und meet/slice.
href (SVGAnimatedString): die Bild-URL.
crossOrigin (string | null): CORS-Modus beim Laden, entspricht dem Attribut crossorigin.
decoding (string): Hinweis zum Dekodieren, "sync", "async" oder "auto".
decode(): gibt ein Promise zurück, das erfüllt wird, sobald das Bild geladen und dekodiert ist.

Die animierbaren Eigenschaften wie x oder width sind keine einfachen Zahlen. Den aktuellen Attributwert liest und schreibst du über .baseVal.value. Den gerade animierten Wert liefert .animVal. Sollen die Werte als Zeichenkette gesetzt werden, ist setAttribute() meist einfacher.

Typische Einsatzfälle: Hintergrund- oder Kartenbilder in interaktiven SVG-Diagrammen, Avatare in Graphen, Texturen per <pattern> und Bilder, die mit clip-path oder mask zugeschnitten werden.

Parameter

Name	Typ	Default	Beschreibung
$x	SVGAnimatedLength	0	X-Koordinate der linken oberen Ecke. Lesen und Schreiben über `x.baseVal.value`.
$y	SVGAnimatedLength	0	Y-Koordinate der linken oberen Ecke.
$width	SVGAnimatedLength	auto	Breite des Bildbereichs. Bei `auto` wird die natürliche Breite des Bildes verwendet.
$height	SVGAnimatedLength	auto	Höhe des Bildbereichs.
$href Pflicht	SVGAnimatedString		URL des Bildes. Das Attribut ist `href`, veraltet ist `xlink:href`.
$preserveAspectRatio	SVGAnimatedPreserveAspectRatio	xMidYMid meet	Steuert, wie das Bild in den Bereich eingepasst wird: Ausrichtung sowie `meet` (einpassen) oder `slice` (auffüllen).
$crossOrigin	string \| null	null	CORS-Modus: `"anonymous"` oder `"use-credentials"`.
$decoding	"sync" \| "async" \| "auto"	"auto"	Hinweis an den Browser, ob das Bild synchron oder asynchron dekodiert werden soll.

Rückgabewert

Typ

SVGImageElement

Beschreibung

Eine Instanz entsteht über document.createElementNS("http://www.w3.org/2000/svg", "image") oder beim Parsen eines <image>-Elements innerhalb von <svg>. Einen öffentlichen Konstruktor gibt es nicht.

Beispiele

Bild per JavaScript in ein SVG einfügen

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
svg.setAttribute('viewBox', '0 0 200 200');
svg.setAttribute('width', '200');
svg.setAttribute('height', '200');

const img = document.createElementNS(SVG_NS, 'image');
img.setAttribute('href', 'https://picsum.photos/400/300');
img.setAttribute('x', '0');
img.setAttribute('y', '0');
img.setAttribute('width', '200');
img.setAttribute('height', '200');
img.setAttribute('preserveAspectRatio', 'xMidYMid slice');

svg.append(img);
document.body.append(svg);

console.log(img instanceof SVGImageElement);

true

Position und Größe über baseVal ändern

const img = document.querySelector('svg image');

// Animierbare Längen: Zugriff über baseVal.value
img.x.baseVal.value = 20;
img.width.baseVal.value = 120;

console.log(img.x.baseVal.value, img.width.baseVal.value);
console.log(img.href.baseVal);

// Ausrichtung auf "oben links, einpassen" setzen
const par = img.preserveAspectRatio.baseVal;
par.align = SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMINYMIN;
par.meetOrSlice = SVGPreserveAspectRatio.SVG_MEETORSLICE_MEET;
console.log(img.getAttribute('preserveAspectRatio'));

20 120 https://picsum.photos/400/300 xMinYMin meet

Bild nachladen und auf Dekodierung warten

const img = document.querySelector('#avatar'); // <image id="avatar">

const swapImage = async (url) => {
  img.crossOrigin = 'anonymous';
  img.setAttribute('href', url);
  try {
    // decode() wartet auf Laden und Dekodieren
    await img.decode();
    console.log('Bild bereit:', img.getBBox().width, 'px breit');
  } catch (err) {
    console.error('Bild konnte nicht geladen werden', err);
  }
};

// Alternative: klassische Events
img.addEventListener('load', () => console.log('load'));
img.addEventListener('error', () => console.log('error'));

swapImage('/img/user-42.png');

load Bild bereit: 64 px breit

Siehe auch

SVGFEImageElement SVGAnimateElement SVGMaskElement HTMLImageElement SVGAElement SVGDiscardElement