SVGAnimatedNumber — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGAnimatedNumber

Beschreibung

SVGAnimatedNumber ist ein Wrapper-Interface des SVG-DOM für Attribute, deren Wert eine einzelne Zahl ist und die per SMIL (<animate>, <set>) animiert werden können. Typische Beispiele sind SVGStopElement.offset, SVGGeometryElement.pathLength, SVGFEOffsetElement.dx/dy, SVGFEGaussianBlurElement.stdDeviationX/stdDeviationY oder die Koeffizienten k1–k4 von SVGFECompositeElement.

Das Interface hat zwei Eigenschaften:

baseVal (number, les- und schreibbar): der statische Grundwert, so wie er im Attribut steht. Beim Setzen wird das zugehörige Attribut im DOM automatisch aktualisiert.
animVal (number, nur lesbar): der aktuell wirksame Wert, sofern gerade eine Animation läuft; ohne Animation entspricht er baseVal.

Man verwendet SVGAnimatedNumber, wenn man numerische SVG-Attribute typsicher als Zahl statt als String über getAttribute()/setAttribute() lesen oder schreiben möchte – etwa um Filter-Parameter oder Farbverlaufs-Stopps dynamisch per Skript zu verändern. Das Objekt wird nie selbst konstruiert, sondern immer über eine Eigenschaft eines SVG-Elements bezogen.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Objekt mit den Eigenschaften baseVal (number, schreibbar) und animVal (number, nur lesbar).

Beispiele

Offset eines Farbverlauf-Stopps auslesen

// <linearGradient id="lg"><stop id="s1" offset="0.25" stop-color="red"/></linearGradient>
const stop = document.getElementById('s1');
const offset = stop.offset; // SVGAnimatedNumber

console.log(offset instanceof SVGAnimatedNumber);
console.log(offset.baseVal);
console.log(offset.animVal);

true 0.25 0.25

Weichzeichner-Stärke per Schieberegler steuern

// <filter id="blur"><feGaussianBlur id="gb" stdDeviation="2"/></filter>
const blur = document.getElementById('gb');
const slider = document.querySelector('#blurSlider');

slider.addEventListener('input', () => {
  const value = Number(slider.value);
  // Beide Achsen getrennt als SVGAnimatedNumber
  blur.stdDeviationX.baseVal = value;
  blur.stdDeviationY.baseVal = value;
  console.log(blur.getAttribute('stdDeviation'));
});

z. B. "5" bzw. "5 5" nach Bewegen des Reglers auf 5

pathLength für Linien-Animation normalisieren

// <path id="p" d="M10 10 L200 10" stroke="black"/>
const path = document.getElementById('p');

// Pfadlänge auf 100 normieren – Dash-Werte gelten dann in Prozent
path.pathLength.baseVal = 100;
path.style.strokeDasharray = '100';
path.style.strokeDashoffset = '100';

console.log(path.getAttribute('pathLength'));
console.log(path.getTotalLength()); // echte Länge bleibt unverändert

"100" 190

Laufende SMIL-Animation beobachten

// <stop id="s2" offset="0"><animate attributeName="offset" from="0" to="1" dur="2s" repeatCount="indefinite"/></stop>
const stop = document.getElementById('s2');

setTimeout(() => {
  console.log('Basis:', stop.offset.baseVal);
  console.log('Animiert:', stop.offset.animVal.toFixed(2));
}, 1000);

Basis: 0 Animiert: 0.50 (in Browsern, die animVal korrekt aktualisieren)

// Wichtig · Fallstricke

animVal ist nicht überall zuverlässig: Chromium-basierte Browser und Safari liefern für animVal häufig einfach den baseVal zurück, auch während einer SMIL-Animation läuft. Firefox gibt den animierten Wert zurück. Den aktuell wirksamen Wert solltest du nicht allein aus animVal ableiten.
animVal ist nur lesbar. Eine Zuweisung wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus.
Wenn du baseVal setzt, wird das Attribut serialisiert. Nicht endliche Werte (NaN, Infinity) führen zu einem TypeError.
Bei Attributen mit zwei Zahlen (z. B. stdDeviation, baseFrequency) gibt es zwei getrennte SVGAnimatedNumber-Eigenschaften (…X/…Y). Listen von Zahlen wie values bei feColorMatrix nutzen dagegen SVGAnimatedNumberList.
CSS-Animationen und die Web Animations API wirken sich nicht auf animVal aus, denn dort werden nur SMIL-Animationen abgebildet.
Das Interface lässt sich nicht direkt instanziieren (new SVGAnimatedNumber() wirft einen TypeError).

Siehe auch

SVGAnimatedLength SVGAnimatedNumberList SVGAnimatedInteger SVGStopElement SVGFEGaussianBlurElement SVGGeometryElement