SVGFEImageElement.preserveAspectRatio — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEImageElement.preserveAspectRatio

Beschreibung

Die Eigenschaft preserveAspectRatio der Schnittstelle SVGFEImageElement gibt Zugriff auf das gleichnamige Attribut eines <feImage>-Filterprimitivs. Dieses Attribut legt fest, wie das referenzierte Bild in den Filter-Teilbereich (x, y, width, height) eingepasst wird: ob das Seitenverhältnis erhalten bleibt, wie das Bild ausgerichtet wird und ob es den Bereich vollständig ausfüllt (slice) oder komplett sichtbar bleibt (meet).

Die Eigenschaft selbst ist schreibgeschützt – du kannst ihr kein neues Objekt zuweisen. Sie liefert jedoch ein SVGAnimatedPreserveAspectRatio-Objekt, dessen baseVal (ein SVGPreserveAspectRatio) veränderbar ist. Über baseVal.align und baseVal.meetOrSlice lassen sich die Werte per Skript ändern; animVal spiegelt den aktuell (ggf. durch SMIL animierten) Wert wider.

Typische Einsatzfälle sind dynamische Filtereffekte, bei denen ein Bild als Textur oder Hintergrund in einen Filter eingespeist wird und die Einpassung je nach Layout zur Laufzeit angepasst werden soll. Alternativ kannst du das Attribut auch direkt per setAttribute('preserveAspectRatio', 'xMidYMid slice') setzen – die Eigenschaft spiegelt die Änderung sofort wider.

Rückgabewert

Typ

SVGAnimatedPreserveAspectRatio

Beschreibung

Objekt mit den Eigenschaften baseVal und animVal (jeweils SVGPreserveAspectRatio mit align und meetOrSlice als numerische Konstanten). Ohne gesetztes Attribut entspricht der Wert xMidYMid meet.

Beispiele

Aktuellen Wert auslesen

// <svg><filter id="f"><feImage id="img" href="bild.png" preserveAspectRatio="xMinYMin slice"/></filter></svg>
const feImage = document.getElementById('img');
const par = feImage.preserveAspectRatio.baseVal;

console.log(par.align === SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMINYMIN);
console.log(par.meetOrSlice === SVGPreserveAspectRatio.SVG_MEETORSLICE_SLICE);

true true

Einpassung per Skript ändern

const feImage = document.querySelector('filter feImage');
const par = feImage.preserveAspectRatio.baseVal;

// Bild zentrieren und vollständig sichtbar halten
par.align = SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMIDYMID;
par.meetOrSlice = SVGPreserveAspectRatio.SVG_MEETORSLICE_MEET;

console.log(feImage.getAttribute('preserveAspectRatio'));

xMidYMid meet

feImage dynamisch erzeugen und Wert prüfen

const SVG_NS = 'http://www.w3.org/2000/svg';
const filter = document.createElementNS(SVG_NS, 'filter');
const feImage = document.createElementNS(SVG_NS, 'feImage');
feImage.setAttribute('href', 'textur.jpg');
feImage.setAttribute('preserveAspectRatio', 'none');
filter.append(feImage);

const { align } = feImage.preserveAspectRatio.baseVal;
console.log(align === SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_NONE);

true

// Wichtig · Fallstricke

Die Eigenschaft ist schreibgeschützt: feImage.preserveAspectRatio = … hat keine Wirkung (im Strict Mode TypeError). Ändere stattdessen baseVal.align/baseVal.meetOrSlice oder das Attribut.
align und meetOrSlice sind Zahlen, keine Strings – vergleiche mit den Konstanten von SVGPreserveAspectRatio (z. B. SVG_PRESERVEASPECTRATIO_XMIDYMID = 6).
Das Zuweisen von SVG_PRESERVEASPECTRATIO_UNKNOWN (0) wirft einen Fehler.
Bei align = none wird meetOrSlice ignoriert; das Bild wird verzerrt.
Wird ein Element statt eines Bildes referenziert (href=\"#id\"), hat preserveAspectRatio in den meisten Browsern keinen Effekt.
In allen modernen Browsern unterstützt; animVal ändert sich nur bei SMIL-Animationen.

Siehe auch

SVGFEImageElement SVGAnimatedPreserveAspectRatio SVGPreserveAspectRatio SVGImageElement.preserveAspectRatio SVGFEImageElement.href PaymentRequestEvent.paymentRequestOrigin SVGFEImageElement.result