SVGAnimatedLength — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGAnimatedLength

Beschreibung

SVGAnimatedLength ist der Typ, den SVG-DOM-Eigenschaften für Längenattribute liefern. Dazu gehören zum Beispiel SVGRectElement.x, width, height, SVGCircleElement.r, cx, cy und SVGSVGElement.width. Solche Attribute lassen sich mit SMIL (<animate>) animieren. Deshalb trennt die Schnittstelle zwei Werte voneinander:

baseVal: ein SVGLength-Objekt mit dem Grundwert des Attributs, also dem Wert im Markup. Dieser Wert ist beschreibbar.
animVal: ein schreibgeschütztes SVGLength-Objekt mit dem Wert, der gerade gilt, während eine Animation läuft. Läuft keine Animation, entspricht er baseVal.

Das SVGLength-Objekt hat mehrere Eigenschaften. value enthält den Wert in Benutzereinheiten, also im Wesentlichen in Pixeln. valueInSpecifiedUnits enthält die Zahl in der angegebenen Einheit, valueAsString den Text, etwa "50%". unitType ist eine Konstante für die Einheit. Mit convertToSpecifiedUnits() und newValueSpecifiedUnits() rechnen Sie Einheiten um oder setzen Wert und Einheit gleichzeitig.

Mit der Schnittstelle lesen und schreiben Sie Geometriewerte typsicher und abhängig von der Einheit. Das ist robuster als getAttribute() und setAttribute(), die nur mit Zeichenketten arbeiten. Prozentwerte und relative Einheiten wie em werden in value automatisch in Benutzereinheiten umgerechnet.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Die Schnittstelle hat keinen Konstruktor. Sie erhalten Instanzen über Längeneigenschaften von SVG-Elementen, z. B. rect.width. Die Eigenschaften baseVal und animVal sind jeweils ein SVGLength.

Beispiele

Grundwert und animierten Wert auslesen

const svg = document.querySelector('svg');
svg.innerHTML = `
  <rect id="box" x="10" y="10" width="100" height="50">
    <animate attributeName="width" from="100" to="300" dur="2s" repeatCount="indefinite" />
  </rect>`;

const rect = document.getElementById('box');
const width = rect.width; // SVGAnimatedLength

console.log(width instanceof SVGAnimatedLength);
console.log('Grundwert:', width.baseVal.value);

// Aktuellen animierten Wert regelmäßig abfragen
setInterval(() => {
  console.log('Animiert:', Math.round(width.animVal.value));
}, 500);

true Grundwert: 100 Animiert: 150 Animiert: 200 ...

Länge per baseVal typsicher ändern

const circle = document.querySelector('circle');

// Radius auf 40 Benutzereinheiten setzen
circle.r.baseVal.value = 40;
console.log(circle.getAttribute('r'));

// Radius auf 10 % setzen (Wert und Einheit gleichzeitig)
circle.r.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 10);
console.log(circle.getAttribute('r'));
console.log(circle.r.baseVal.valueAsString);

40 10% 10%

Prozentwerte in Pixel umrechnen

const svg = document.querySelector('svg'); // z. B. 400 × 200 px
const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
rect.setAttribute('width', '50%');
rect.setAttribute('height', '25%');
svg.append(rect);

const { width, height } = rect;
console.log(width.baseVal.valueAsString);  // Angabe im Markup
console.log(width.baseVal.value);          // umgerechnet in Benutzereinheiten

// Dauerhaft in Pixel umwandeln
height.baseVal.convertToSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PX);
console.log(rect.getAttribute('height'));

50% 200 50px

// Wichtig · Fallstricke

animVal ist schreibgeschützt. Wenn Sie versuchen, animVal.value zu setzen, wird im Strict Mode ein DOMException vom Typ NoModificationAllowedError ausgelöst. Änderungen gehören immer an baseVal.
Nicht mit CSS-Animationen verwechseln. animVal zeigt nur SMIL-Animationen an. Ändern Sie Geometrieeigenschaften wie width oder r über CSS oder die Web Animations API, sehen Sie die Änderung nicht in animVal. Den tatsächlich gerenderten Wert erhalten Sie dann mit getComputedStyle() oder getBBox().
Umrechnung relativer Einheiten. Für Prozentangaben und em/ex braucht value einen Bezugsrahmen. Ist das Element nicht im Dokument eingehängt oder hat es keinen Viewport, kann das Ergebnis 0 sein oder eine Ausnahme ausgelöst werden.
Live-Objekte: baseVal ist an das Attribut gebunden. Ändern Sie das Attribut mit setAttribute(), ändert sich das bereits geholte SVGLength-Objekt mit.
Kompatibilität: Die Schnittstelle wird von allen aktuellen Browsern unterstützt. Die SMIL-Unterstützung ist gut. Der Internet Explorer kannte SMIL aber nicht, dort war animVal immer gleich baseVal.

Siehe auch

SVGLength SVGAnimatedLengthList SVGAnimatedNumber SVGRectElement SVGCircleElement SVGGraphicsElement.getBBox()