SVGViewElement.preserveAspectRatio — Eigenschaft · JavaScript-Referenz

Signatur

get SVGViewElement.preserveAspectRatio

Beschreibung

Die schreibgeschützte Eigenschaft preserveAspectRatio der Schnittstelle SVGViewElement gibt Zugriff auf das gleichnamige Attribut eines <view>-Elements. Ein <view> legt eine benannte Ansicht innerhalb einer SVG-Grafik fest. Man springt über einen Fragment-Bezeichner wie grafik.svg#detail dorthin. Das Attribut bestimmt, wie der viewBox dieser Ansicht in den verfügbaren Anzeigebereich eingepasst wird.

Zurückgegeben wird kein String, sondern ein SVGAnimatedPreserveAspectRatio-Objekt. Es hat zwei Eigenschaften: baseVal für den im Markup gesetzten bzw. per Skript geänderten Grundwert und animVal für den aktuell animierten Wert. Beide sind vom Typ SVGPreserveAspectRatio mit den numerischen Feldern align (z. B. SVG_PRESERVEASPECTRATIO_XMIDYMID) und meetOrSlice (SVG_MEETORSLICE_MEET oder SVG_MEETORSLICE_SLICE).

Die Eigenschaft selbst kann man nicht neu zuweisen. Die Felder von baseVal lassen sich aber ändern, und die Änderung wirkt sofort auf das Attribut zurück. Das braucht man vor allem, wenn Ansichten dynamisch erzeugt oder angepasst werden, etwa für Zoom-Stufen oder Kartenausschnitte in interaktiven SVG-Grafiken.

Rückgabewert

Typ

SVGAnimatedPreserveAspectRatio

Beschreibung

Objekt mit baseVal und animVal (jeweils SVGPreserveAspectRatio). Beide enthalten die numerischen Felder align und meetOrSlice.

Beispiele

Ausrichtung einer Ansicht auslesen

// <svg><view id="detail" viewBox="0 0 50 50" preserveAspectRatio="xMinYMin slice"/></svg>
const view = document.getElementById('detail');
const { align, meetOrSlice } = view.preserveAspectRatio.baseVal;

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

true true

Numerische Werte in lesbare Namen übersetzen

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

const describe = (viewEl) => {
  const par = viewEl.preserveAspectRatio.baseVal;
  return `${ALIGN[par.align]} ${MOS[par.meetOrSlice]}`;
};

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

xMidYMid meet

Ausrichtung per Skript ändern

const view = document.querySelector('view#karte');
const par = view.preserveAspectRatio.baseVal;

par.align = SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMAXYMAX;
par.meetOrSlice = SVGPreserveAspectRatio.SVG_MEETORSLICE_SLICE;

// Das Attribut wird automatisch aktualisiert
console.log(view.getAttribute('preserveAspectRatio'));

xMaxYMax slice

// Wichtig · Fallstricke

Schreibgeschützt: view.preserveAspectRatio = '…' hat keine Wirkung und wirft im Strict Mode einen TypeError. Ändere stattdessen baseVal.align bzw. baseVal.meetOrSlice oder nutze setAttribute('preserveAspectRatio', 'xMidYMid slice').
animVal ist schreibgeschützt. Wer einen Wert setzt, erhält eine NoModificationAllowedError-Ausnahme.
Wird align oder meetOrSlice auf 0 (…_UNKNOWN) gesetzt, wird ein TypeError (in älteren Browsern ein NotSupportedError) geworfen.
Das Attribut wirkt nur, wenn der <view> auch einen viewBox hat und über einen Fragment-Bezeichner (#id) aktiviert wird.
Die Browser-Unterstützung ist gut (Chrome, Firefox, Safari, Edge). Das Rendern von <view>-Fragmenten in <img> und CSS-Hintergründen unterscheidet sich aber historisch leicht zwischen den Browsern.

Siehe auch

SVGViewElement SVGViewElement.viewBox SVGAnimatedPreserveAspectRatio SVGPreserveAspectRatio SVGSVGElement.preserveAspectRatio Window.documentPictureInPicture