SVGPreserveAspectRatio.align — Eigenschaft · JavaScript-Referenz

Signatur

SVGPreserveAspectRatio.align

Beschreibung

Die Eigenschaft align eines SVGPreserveAspectRatio-Objekts gibt als unsigned short an, wie der Inhalt einer viewBox im Darstellungsbereich (Viewport) ausgerichtet wird. Sie entspricht dem ersten Teil des Attributs preserveAspectRatio, also etwa xMidYMid oder none. Den zweiten Teil (meet/slice) liefert meetOrSlice.

An das Objekt kommt man über ein SVGAnimatedPreserveAspectRatio, z. B. svgElement.preserveAspectRatio.baseVal (statischer Attributwert) oder .animVal (aktuell animierter Wert). Das Attribut gibt es auf <svg>, <image>, <symbol>, <marker>, <pattern>, <view> und <feImage>.

Diese Zahlenwerte sind möglich. Sie stehen als Konstanten auf SVGPreserveAspectRatio zur Verfügung:

0 – SVG_PRESERVEASPECTRATIO_UNKNOWN
1 – SVG_PRESERVEASPECTRATIO_NONE (keine gleichmäßige Skalierung, der Inhalt wird verzerrt)
2–4 – XMINYMIN, XMIDYMIN, XMAXYMIN
5–7 – XMINYMID, XMIDYMID (Standardwert), XMAXYMID
8–10 – XMINYMAX, XMIDYMAX, XMAXYMAX

MDN beschreibt die Eigenschaft als schreibgeschützt. Nach SVG 2 lässt sie sich aber über baseVal setzen, und das Attribut im DOM wird dann entsprechend aktualisiert. Über animVal ist sie tatsächlich nur lesbar. Die Eigenschaft ist nützlich, wenn man das Skalierungsverhalten auswerten oder zur Laufzeit ändern will, ohne den Attribut-String selbst zu parsen.

Rückgabewert

Typ

number

Beschreibung

Eine Ganzzahl von 0 bis 10, die einer der Konstanten SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_* entspricht. Fehlt das Attribut, ist der Wert 6 (xMidYMid).

Beispiele

Ausrichtung eines SVG-Elements auslesen

// <svg id="logo" viewBox="0 0 100 50" preserveAspectRatio="xMinYMax slice"></svg>
const svg = document.getElementById('logo');
const par = svg.preserveAspectRatio.baseVal;

console.log(par.align);
console.log(par.align === SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMINYMAX);
console.log(par.meetOrSlice === SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_SLICE);

8 true true

Zahlenwert in lesbaren Attribut-Namen übersetzen

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

const describeAlign = (el) => ALIGN_NAMES[el.preserveAspectRatio.baseVal.align];

// Ein neues Element ohne Attribut liefert den Standardwert
const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
console.log(describeAlign(svg));

svg.setAttribute('preserveAspectRatio', 'none');
console.log(describeAlign(svg));

xMidYMid none

Ausrichtung zur Laufzeit ändern (z. B. Bild oben links verankern)

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

try {
  par.align = SVGPreserveAspectRatio.SVG_PRESERVEASPECTRATIO_XMINYMIN;
  // Das DOM-Attribut wird automatisch angepasst
  console.log(img.getAttribute('preserveAspectRatio'));
} catch (err) {
  // Ältere Implementierungen behandeln align als schreibgeschützt
  img.setAttribute('preserveAspectRatio', 'xMinYMin meet');
}

xMinYMin meet

// Wichtig · Fallstricke

Schreibschutz: Über animVal ist align immer nur lesbar. Wer den Wert schreibend ändern will, sollte baseVal verwenden. Am sichersten ist setAttribute('preserveAspectRatio', …), weil sich ältere Engines beim Setzen unterschiedlich verhalten.
Ungültige Werte: Wer 0 (UNKNOWN) oder eine Zahl außerhalb von 1–10 zuweist, bekommt je nach Browser einen Fehler (TypeError bzw. DOMException). Der Wert wird dann nicht übernommen.
Wirkung nur mit viewBox: Bei <svg>, <symbol> und <marker> hat align nur dann eine sichtbare Wirkung, wenn eine viewBox gesetzt ist. Ausgelesen wird der Wert trotzdem korrekt.
Ist align gleich SVG_PRESERVEASPECTRATIO_NONE, wird meetOrSlice ignoriert.
Vergleiche besser mit den benannten Konstanten als mit fest eingetragenen Zahlen. Das macht den Code lesbarer.
Die Eigenschaft wird von allen aktuellen Browsern unterstützt.

Siehe auch

SVGPreserveAspectRatio SVGPreserveAspectRatio.meetOrSlice SVGAnimatedPreserveAspectRatio SVGSVGElement.preserveAspectRatio SVGImageElement.preserveAspectRatio SVGSVGElement.viewBox ServiceWorkerRegistration.sync