SVGImageElement.preserveAspectRatio — Eigenschaft · JavaScript-Referenz

Signatur

SVGImageElement.preserveAspectRatio

Beschreibung

Die Eigenschaft preserveAspectRatio eines SVGImageElement gibt den Zugriff auf das gleichnamige Attribut des <image>-Elements frei. Dieses Attribut legt fest, wie ein eingebettetes Rasterbild oder eine SVG-Grafik in den durch x, y, width und height vorgegebenen Bereich eingepasst wird: zentriert, an einer Ecke ausgerichtet, vollständig sichtbar (meet), bereichsfüllend mit Beschnitt (slice) oder verzerrt (none).

Die Eigenschaft selbst ist schreibgeschützt: Das zurückgegebene SVGAnimatedPreserveAspectRatio-Objekt kann nicht ersetzt werden. Es besitzt die Unterobjekte baseVal (der im Attribut hinterlegte Grundwert, veränderbar) und animVal (der aktuelle, ggf. durch SMIL-Animation veränderte Wert, nur lesbar). Beide sind vom Typ SVGPreserveAspectRatio mit den numerischen Eigenschaften align und meetOrSlice.

Typische Einsatzfälle sind Bildergalerien oder Diagramme in SVG, bei denen per Skript zwischen „Einpassen“ und „Ausfüllen“ gewechselt werden soll, oder das Auslesen der aktuellen Ausrichtung, ohne den Attribut-String selbst parsen zu müssen.

Rückgabewert

Typ

SVGAnimatedPreserveAspectRatio

Beschreibung

Ein Objekt mit baseVal und animVal (jeweils SVGPreserveAspectRatio). align ist eine Konstante wie SVG_PRESERVEASPECTRATIO_XMIDYMID (6), meetOrSlice ist SVG_MEETORSLICE_MEET (1) oder SVG_MEETORSLICE_SLICE (2).

Beispiele

Aktuelle Ausrichtung auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const img = document.createElementNS(svgNS, 'image');
img.setAttribute('href', 'foto.jpg');
img.setAttribute('width', '200');
img.setAttribute('height', '100');
img.setAttribute('preserveAspectRatio', 'xMinYMid slice');

const { baseVal } = img.preserveAspectRatio;
console.log(baseVal.align === SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMINYMID);
console.log(baseVal.meetOrSlice === SVGPreserveAspectRatio.SVG_MEETORSLICE_SLICE);

true true

Zwischen „Einpassen“ und „Ausfüllen“ umschalten

const img = document.querySelector('svg image');
const toggleBtn = document.querySelector('#toggle-fit');

toggleBtn.addEventListener('click', () => {
  const pa = img.preserveAspectRatio.baseVal;
  pa.meetOrSlice = pa.meetOrSlice === SVGPreserveAspectRatio.SVG_MEETORSLICE_MEET
    ? SVGPreserveAspectRatio.SVG_MEETORSLICE_SLICE
    : SVGPreserveAspectRatio.SVG_MEETORSLICE_MEET;
  // Das Attribut wird automatisch synchronisiert
  console.log(img.getAttribute('preserveAspectRatio'));
});

xMidYMid slice

Verzerrtes Strecken aktivieren

const img = document.querySelector('svg image');
img.preserveAspectRatio.baseVal.align =
  SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_NONE;
console.log(img.getAttribute('preserveAspectRatio'));

none

// Wichtig · Fallstricke

Eine direkte Zuweisung wie img.preserveAspectRatio = 'none' ist wirkungslos (im Strict Mode TypeError). Ändere stattdessen baseVal.align/baseVal.meetOrSlice oder nutze setAttribute('preserveAspectRatio', …).
animVal ist schreibgeschützt; Schreibzugriffe lösen einen NoModificationAllowedError aus.
Die Zuweisung von SVG_PRESERVEASPECTRATIO_UNKNOWN (0) bzw. SVG_MEETORSLICE_UNKNOWN (0) wirft einen Fehler.
Bei align = none wird meetOrSlice ignoriert. Ohne Attribut gilt der Standardwert xMidYMid meet.
Bei eingebetteten SVG-Dateien mit eigenem viewBox wirkt das Attribut ebenfalls; fehlt der viewBox, kann das Ergebnis je nach Browser abweichen.
Die Eigenschaft wird von allen modernen Browsern unterstützt; das Element muss im SVG-Namensraum erzeugt werden (createElementNS), sonst existiert sie nicht.

Siehe auch

SVGImageElement SVGAnimatedPreserveAspectRatio SVGPreserveAspectRatio SVGSVGElement.preserveAspectRatio SVGImageElement.width Element.setAttribute() SVGImageElement.crossOrigin