SVGPatternElement.preserveAspectRatio — Eigenschaft · JavaScript-Referenz

Signatur

SVGPatternElement.preserveAspectRatio

Beschreibung

Die Eigenschaft preserveAspectRatio der Schnittstelle SVGPatternElement spiegelt das gleichnamige Attribut eines <pattern>-Elements wider. Sie legt fest, wie der Inhalt des Musters (definiert über viewBox) in die Musterkachel (width/height) eingepasst wird – also ob das Seitenverhältnis erhalten bleibt und wie der Inhalt ausgerichtet wird.

Die Eigenschaft selbst ist schreibgeschützt: Sie gibt ein SVGAnimatedPreserveAspectRatio-Objekt zurück. Dessen baseVal (ein SVGPreserveAspectRatio) enthält den im Markup gesetzten Wert und ist beschreibbar, animVal enthält den aktuell (ggf. per SMIL animierten) wirksamen Wert und ist schreibgeschützt.

Über baseVal.align (z. B. SVG_PRESERVEASPECTRATIO_XMIDYMID) und baseVal.meetOrSlice (SVG_MEETORSLICE_MEET oder SVG_MEETORSLICE_SLICE) lässt sich die Einpassung numerisch auslesen und ändern. Das ist nützlich, wenn Muster dynamisch erzeugt oder in Editoren manipuliert werden. Wirkung hat die Eigenschaft nur, wenn das Muster ein viewBox-Attribut besitzt.

Rückgabewert

Typ

SVGAnimatedPreserveAspectRatio

Beschreibung

Objekt mit baseVal (beschreibbarer Grundwert) und animVal (schreibgeschützter, aktuell wirksamer Wert), jeweils vom Typ SVGPreserveAspectRatio mit den Feldern align und meetOrSlice.

Beispiele

Ausrichtung und meet/slice auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const pattern = document.createElementNS(svgNS, 'pattern');
pattern.setAttribute('viewBox', '0 0 10 10');
pattern.setAttribute('preserveAspectRatio', 'xMidYMid slice');

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

true true

Einpassung per Skript ändern

// <pattern id="dots" viewBox="0 0 10 10" width="20" height="40" patternUnits="userSpaceOnUse">…</pattern>
const pattern = document.getElementById('dots');
const par = pattern.preserveAspectRatio.baseVal;

// Links oben ausrichten, vollständig sichtbar (meet)
par.align = SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMINYMIN;
par.meetOrSlice = SVGPreserveAspectRatio.SVG_MEETORSLICE_MEET;

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

xMinYMin meet

Verzerrung zulassen (none)

const pattern = document.querySelector('pattern');
pattern.preserveAspectRatio.baseVal.align =
  SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_NONE;

// Alternativ direkt über das Attribut:
// pattern.setAttribute('preserveAspectRatio', 'none');
console.log(pattern.preserveAspectRatio.animVal.align);

1

// Wichtig · Fallstricke

Die Eigenschaft selbst kann nicht neu zugewiesen werden (pattern.preserveAspectRatio = … bleibt wirkungslos bzw. wirft im Strict Mode). Änderungen erfolgen über baseVal oder setAttribute().
Ohne viewBox auf dem <pattern> hat preserveAspectRatio keine sichtbare Wirkung.
Standardwert ist xMidYMid meet. Ein Setzen von align auf SVG_PRESERVEASPECTRATIO_UNKNOWN (0) ist unzulässig und löst einen Fehler aus.
animVal ist schreibgeschützt; Schreibversuche lösen einen NoModificationAllowedError aus.
In allen modernen Browsern unterstützt; Elemente müssen im SVG-Namensraum erzeugt werden (createElementNS), sonst existiert die Eigenschaft nicht.

Siehe auch

SVGPatternElement SVGPatternElement.viewBox SVGAnimatedPreserveAspectRatio SVGPreserveAspectRatio SVGSVGElement.preserveAspectRatio MediaTrackSettings.aspectRatio SVGPatternElement.href