SVGAnimatedPreserveAspectRatio — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGAnimatedPreserveAspectRatio

Beschreibung

Die Schnittstelle SVGAnimatedPreserveAspectRatio steht für SVG-Attribute vom Typ SVGPreserveAspectRatio, die sich per SMIL (<animate>, <set>) animieren lassen. Der wichtigste Fall ist das Attribut preserveAspectRatio. Es legt fest, wie der Inhalt eines viewBox bzw. eines Bildes in den verfügbaren Viewport eingepasst wird.

Ein solches Objekt erhältst du über die Eigenschaft preserveAspectRatio von Elementen wie SVGSVGElement, SVGImageElement, SVGSymbolElement, SVGMarkerElement, SVGPatternElement, SVGViewElement und SVGFEImageElement. Einen Konstruktor gibt es nicht.

Das Objekt hat zwei schreibgeschützte Eigenschaften:

baseVal (SVGPreserveAspectRatio): der Basiswert, also der Wert ohne Animation. Seine Felder align und meetOrSlice kannst du ändern. Die Änderung wird dann ins Attribut zurückgeschrieben.
animVal (SVGPreserveAspectRatio): der aktuell wirksame, gegebenenfalls animierte Wert. Er ist nur lesbar.

Nutze die Schnittstelle, wenn du Ausrichtung und Skalierung von SVG-Inhalten per Skript auslesen oder typsicher ändern willst, ohne Attribut-Strings selbst zu zerlegen.

Rückgabewert

Typ

SVGAnimatedPreserveAspectRatio

Beschreibung

Wird von der Eigenschaft element.preserveAspectRatio geliefert. Das Objekt enthält baseVal und animVal, beide vom Typ SVGPreserveAspectRatio.

Beispiele

Objekt holen und Werte auslesen

const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
svg.setAttribute('viewBox', '0 0 100 50');
svg.setAttribute('preserveAspectRatio', 'xMinYMid slice');
document.body.append(svg);

const par = svg.preserveAspectRatio; // SVGAnimatedPreserveAspectRatio
const { align, meetOrSlice } = par.baseVal;

console.log(align === SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMINYMID);
console.log(meetOrSlice === SVGPreserveAspectRatio.SVG_MEETORSLICE_SLICE);

true true

Ausrichtung per Skript ändern

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

// Bild zentrieren und vollständig sichtbar skalieren (entspricht "xMidYMid meet")
base.align = SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMIDYMID;
base.meetOrSlice = SVGPreserveAspectRatio.SVG_MEETORSLICE_MEET;

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

xMidYMid meet

Numerische Konstanten in lesbaren Text umwandeln

const ALIGN = ['unknown', 'none', 'xMinYMin', 'xMidYMin', 'xMaxYMin',
  'xMinYMid', 'xMidYMid', 'xMaxYMid', 'xMinYMax', 'xMidYMax', 'xMaxYMax'];
const MOS = ['unknown', 'meet', 'slice'];

const describe = (el) => {
  const { align, meetOrSlice } = el.preserveAspectRatio.animVal;
  return `${ALIGN[align]} ${MOS[meetOrSlice]}`;
};

const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
console.log(describe(svg)); // Standardwert

xMidYMid meet

// Wichtig · Fallstricke

baseVal und animVal selbst sind schreibgeschützt. Ein Ausdruck wie el.preserveAspectRatio.baseVal = … hat keine Wirkung (im Strict Mode wirft er einen TypeError). Ändere stattdessen die Felder align und meetOrSlice von baseVal.
Die Felder von animVal sind nur lesbar. Ein Schreibversuch wirft eine NoModificationAllowedError-DOMException.
Wird align oder meetOrSlice auf den Wert 0 (UNKNOWN) gesetzt, wirft die Zuweisung einen TypeError.
Bei align = SVG_PRESERVEASPECTRATIO_NONE wird meetOrSlice ignoriert: Der Inhalt wird dann ungleichmäßig gestreckt.
Ohne gesetztes Attribut ist der Standardwert xMidYMid meet.
Die Schnittstelle wird in allen modernen Browsern unterstützt. SMIL-Animationen von preserveAspectRatio sind selten. Deshalb sind animVal und baseVal in der Praxis fast immer gleich.
Als einfache Alternative kannst du auch setAttribute('preserveAspectRatio', 'xMaxYMax slice') verwenden.

Siehe auch

SVGPreserveAspectRatio SVGSVGElement SVGImageElement SVGAnimatedRect SVGMarkerElement SVGPatternElement