Signatur
Beschreibung
SVGPreserveAspectRatio ist die DOM-Darstellung des Attributs preserveAspectRatio. Das Attribut gibt an, wie der Inhalt einer viewBox (bei <svg>, <symbol>, <marker>, <pattern>, <view>) oder ein Rasterbild (<image>, <feImage>) in den verfügbaren Darstellungsbereich eingepasst wird, wenn die Seitenverhältnisse nicht übereinstimmen.
Eine Instanz erzeugt man nicht selbst. Man erhält sie über die Eigenschaft preserveAspectRatio eines Elements. Diese liefert ein SVGAnimatedPreserveAspectRatio mit baseVal (der beschreibbare Attributwert) und animVal (der aktuelle, eventuell animierte Wert, nur lesbar).
Die Schnittstelle hat zwei numerische Eigenschaften:
align: die Ausrichtung, z. B.SVG_PRESERVEASPECTRATIO_XMIDYMID(6) fürxMidYMidoderSVG_PRESERVEASPECTRATIO_NONE(1) fürnone.meetOrSlice:SVG_MEETORSLICE_MEET(1) passt den Inhalt vollständig ein (wieobject-fit: contain),SVG_MEETORSLICE_SLICE(2) füllt die Fläche und schneidet Überstehendes ab (wieobject-fit: cover).
Die Konstanten gibt es sowohl am Interface-Objekt (SVGPreserveAspectRatio.SVG_MEETORSLICE_SLICE) als auch an jeder Instanz. Wenn man baseVal ändert, wird das Attribut im Markup sofort mit aktualisiert.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $align Pflicht | number (unsigned short) | 6 (SVG_PRESERVEASPECTRATIO_XMIDYMID) | Ausrichtung. Werte: 0 UNKNOWN, 1 NONE, 2 XMINYMIN, 3 XMIDYMIN, 4 XMAXYMIN, 5 XMINYMID, 6 XMIDYMID, 7 XMAXYMID, 8 XMINYMAX, 9 XMIDYMAX, 10 XMAXYMAX. |
| $meetOrSlice Pflicht | number (unsigned short) | 1 (SVG_MEETORSLICE_MEET) | Skalierungsart: 0 UNKNOWN, 1 MEET (einpassen), 2 SLICE (füllen und beschneiden). Bei align = NONE ohne Wirkung. |
Rückgabewert
element.preserveAspectRatio.baseVal bzw. .animVal. Ein Konstruktor lässt sich nicht aufrufen.Beispiele
Aktuellen Wert auslesen und als Attribut-String darstellen
const svg = document.querySelector('svg');
const par = svg.preserveAspectRatio.baseVal;
const alignNames = ['unknown', 'none', 'xMinYMin', 'xMidYMin', 'xMaxYMin',
'xMinYMid', 'xMidYMid', 'xMaxYMid', 'xMinYMax', 'xMidYMax', 'xMaxYMax'];
const meetNames = ['unknown', 'meet', 'slice'];
const toString = (p) => p.align === SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_NONE
? 'none'
: `${alignNames[p.align]} ${meetNames[p.meetOrSlice]}`;
// Ohne gesetztes Attribut gilt der Standardwert
console.log(toString(par));Hintergrundgrafik wie object-fit: cover skalieren
// <svg id="hero" viewBox="0 0 1600 900" width="100%" height="300">…</svg>
const hero = document.getElementById('hero');
const par = hero.preserveAspectRatio.baseVal;
par.align = SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMIDYMIN;
par.meetOrSlice = SVGPreserveAspectRatio.SVG_MEETORSLICE_SLICE;
// Das Attribut wird mit aktualisiert
console.log(hero.getAttribute('preserveAspectRatio'));Bild in <image> verzerrt einpassen (none)
const img = document.querySelector('svg image');
const par = img.preserveAspectRatio.baseVal;
par.align = par.SVG_PRESERVEASPECTRATIO_NONE; // Konstante auch an der Instanz
console.log(img.getAttribute('preserveAspectRatio'));
console.log(img.preserveAspectRatio.animVal.align);// Wichtig · Fallstricke
- Kein Konstruktor:
new SVGPreserveAspectRatio()wirft einenTypeError. Das globale Objekt ist nur für die Konstanten da. - UNKNOWN-Werte: Wenn man
alignodermeetOrSliceauf0(UNKNOWN) oder auf einen ungültigen Wert setzt, wird ein Fehler geworfen (je nach BrowserTypeErroroderNotSupportedError). animValist nur lesbar: Schreibversuche aufanimValwerfen einenNoModificationAllowedError. Änderungen immer überbaseValvornehmen.- Ohne
viewBoxhatpreserveAspectRatiobei<svg>keine sichtbare Wirkung. - Oft ist
setAttribute('preserveAspectRatio', 'xMidYMid slice')einfacher. Das Objekt-Interface lohnt sich, wenn man Werte auslesen und vergleichen will. - Kompatibilität: wird seit Langem von allen modernen Browsern unterstützt. Der Internet Explorer unterstützt es ab Version 9.