Signatur
Beschreibung
Die Eigenschaft preserveAspectRatio der Schnittstelle SVGSymbolElement spiegelt das gleichnamige Attribut eines <symbol>-Elements wider. Sie legt fest, wie der Inhalt des Symbols (definiert durch seine viewBox) in den Darstellungsbereich eingepasst wird, den ein referenzierendes <use>-Element über width und height vorgibt.
Zurückgegeben wird kein String, sondern ein SVGAnimatedPreserveAspectRatio-Objekt. Es besitzt zwei Eigenschaften: baseVal (der im Attribut gesetzte Wert) und animVal (der aktuelle, ggf. durch SMIL-Animation veränderte Wert). Beide sind vom Typ SVGPreserveAspectRatio mit den numerischen Feldern align und meetOrSlice.
Die Eigenschaft selbst ist schreibgeschützt – das Objekt kann also nicht ersetzt werden. Die Felder von baseVal lassen sich jedoch direkt ändern, was das Attribut im DOM aktualisiert. Alternativ setzt man das Attribut klassisch per setAttribute('preserveAspectRatio', …).
Typische Einsatzfälle sind Icon-Sprites, bei denen man zur Laufzeit prüfen oder umschalten möchte, ob ein Symbol verzerrt, zentriert (xMidYMid meet) oder beschnitten (slice) dargestellt wird.
Rückgabewert
baseVal und animVal (je SVGPreserveAspectRatio). align ist eine Konstante wie SVG_PRESERVEASPECTRATIO_XMIDYMID (6), meetOrSlice ist SVG_MEETORSLICE_MEET (1) oder SVG_MEETORSLICE_SLICE (2). Ohne Attribut gilt der Standard xMidYMid meet.Beispiele
Aktuellen Wert eines Symbols auslesen
// <svg><symbol id="icon-star" viewBox="0 0 24 24" preserveAspectRatio="xMinYMid slice">…</symbol></svg>
const symbol = document.getElementById('icon-star');
const { align, meetOrSlice } = symbol.preserveAspectRatio.baseVal;
console.log(align === SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMINYMID);
console.log(meetOrSlice === SVGPreserveAspectRatio.SVG_MEETORSLICE_SLICE);Numerische Werte in lesbaren Attributtext umwandeln
const ALIGN = ['unknown', 'none', 'xMinYMin', 'xMidYMin', 'xMaxYMin',
'xMinYMid', 'xMidYMid', 'xMaxYMid', 'xMinYMax', 'xMidYMax', 'xMaxYMax'];
const MOS = ['unknown', 'meet', 'slice'];
const describe = (symbolEl) => {
const { align, meetOrSlice } = symbolEl.preserveAspectRatio.baseVal;
return align === 1 ? 'none' : `${ALIGN[align]} ${MOS[meetOrSlice]}`;
};
// Symbol ohne Attribut -> Standardwert
const ns = 'http://www.w3.org/2000/svg';
const sym = document.createElementNS(ns, 'symbol');
console.log(describe(sym));Darstellung eines Sprite-Icons zur Laufzeit umschalten
const symbol = document.querySelector('symbol#hero');
const par = symbol.preserveAspectRatio.baseVal;
// Von "meet" (einpassen) auf "slice" (füllen und beschneiden) wechseln
par.align = SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMIDYMID;
par.meetOrSlice = SVGPreserveAspectRatio.SVG_MEETORSLICE_SLICE;
console.log(symbol.getAttribute('preserveAspectRatio'));
// Äquivalent per Attribut:
// symbol.setAttribute('preserveAspectRatio', 'xMidYMid slice');// Wichtig · Fallstricke
- Schreibgeschützt:
symbol.preserveAspectRatio = 'none'hat keine Wirkung (im Strict ModeTypeError). Ändern Sie stattdessenbaseVal.align/baseVal.meetOrSliceoder nutzen SiesetAttribute(). - Nur mit
viewBoxwirksam: Hat das<symbol>keineviewBox, beeinflusstpreserveAspectRatiodie Darstellung nicht. - Die Werte
0(UNKNOWN) dürfen nicht zugewiesen werden – das wirft einen Fehler. - Ist
aligngleichSVG_PRESERVEASPECTRATIO_NONE, wirdmeetOrSliceignoriert; der Inhalt wird verzerrt gestreckt. - Elemente müssen mit
createElementNS('http://www.w3.org/2000/svg', 'symbol')erzeugt werden, sonst entsteht keinSVGSymbolElementund die Eigenschaft fehlt. - Kompatibilität: In allen aktuellen Browsern (Chrome, Firefox, Safari, Edge) unterstützt;
animValentspricht meistbaseVal, da SMIL-Animationen dieses Attributs selten sind.