SVGSVGElement.preserveAspectRatio — Eigenschaft · JavaScript-Referenz

Signatur

SVGSVGElement.preserveAspectRatio

Beschreibung

Die Eigenschaft preserveAspectRatio eines SVGSVGElement gibt ein SVGAnimatedPreserveAspectRatio-Objekt zurück. Es legt fest, wie der Inhalt der viewBox in den Anzeigebereich (Viewport) des <svg>-Elements eingepasst wird, wenn die Seitenverhältnisse nicht übereinstimmen.

Das Objekt hat zwei Eigenschaften: baseVal (der im Attribut gesetzte Wert, veränderbar) und animVal (der aktuelle, ggf. animierte Wert, nur lesbar). Beide sind vom Typ SVGPreserveAspectRatio mit den numerischen Eigenschaften align und meetOrSlice.

Schreibgeschützt ist nur die Eigenschaft selbst. Sie können ihr also kein neues Objekt zuweisen. Den Wert ändern Sie über baseVal.align bzw. baseVal.meetOrSlice oder direkt mit setAttribute('preserveAspectRatio', ...). Das ist praktisch für responsive Grafiken, Diagramme oder Bildausschnitte, die je nach Layout „einpassen“ (meet) oder „füllen und beschneiden“ (slice) sollen.

Rückgabewert

Typ

SVGAnimatedPreserveAspectRatio

Beschreibung

Objekt mit baseVal und animVal (jeweils SVGPreserveAspectRatio). align ist eine der Konstanten SVG_PRESERVEASPECTRATIO_NONE (1) bis SVG_PRESERVEASPECTRATIO_XMAXYMAX (10); meetOrSlice ist SVG_MEETORSLICE_MEET (1) oder SVG_MEETORSLICE_SLICE (2).

Beispiele

Aktuellen Wert auslesen

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

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

true true

Numerische Werte in Attribut-Text umwandeln

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

const describe = (svgEl) => {
  const { align, meetOrSlice } = svgEl.preserveAspectRatio.baseVal;
  return `${ALIGN_NAMES[align]} ${MEET_NAMES[meetOrSlice]}`;
};

const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
svg.setAttribute('viewBox', '0 0 200 100');
console.log(describe(svg)); // Standardwert
svg.setAttribute('preserveAspectRatio', 'xMinYMax meet');
console.log(describe(svg));

xMidYMid meet xMinYMax meet

Zwischen Einpassen und Füllen umschalten

const svg = document.querySelector('svg.hero');
const toggle = document.querySelector('#fill-toggle');

toggle.addEventListener('change', () => {
  const par = svg.preserveAspectRatio.baseVal;
  par.align = SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMIDYMID;
  par.meetOrSlice = toggle.checked
    ? SVGPreserveAspectRatio.SVG_MEETORSLICE_SLICE
    : SVGPreserveAspectRatio.SVG_MEETORSLICE_MEET;
  // Das Attribut wird automatisch synchronisiert
  console.log(svg.getAttribute('preserveAspectRatio'));
});

xMidYMid slice (bei aktivierter Checkbox)

// Wichtig · Fallstricke

Nur mit viewBox wirksam: Hat das <svg>-Element kein viewBox-Attribut, hat preserveAspectRatio keine sichtbare Wirkung.
Schreibgeschützt: Eine Zuweisung wie svg.preserveAspectRatio = ... wird ignoriert (im Strict Mode gibt es einen TypeError). Ändern Sie stattdessen baseVal oder das Attribut.
animVal ist nur lesbar. Schreibversuche lösen eine NoModificationAllowedError-DOMException aus.
Bei align = SVG_PRESERVEASPECTRATIO_NONE wird der Inhalt verzerrt, der Wert von meetOrSlice wird dann ignoriert.
Den Wert SVG_PRESERVEASPECTRATIO_UNKNOWN (0) dürfen Sie nicht zuweisen, sonst gibt es einen TypeError.
Die Eigenschaft wird von allen modernen Browsern unterstützt. Dieselbe Eigenschaft gibt es auch bei SVGImageElement, SVGSymbolElement, SVGMarkerElement, SVGPatternElement und SVGViewElement.

Siehe auch

SVGSVGElement SVGSVGElement.viewBox SVGAnimatedPreserveAspectRatio SVGPreserveAspectRatio Element.setAttribute() PopStateEvent.hasUAVisualTransition