SVGAnimatedNumberList — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGAnimatedNumberList

Beschreibung

SVGAnimatedNumberList ist der DOM-Datentyp für SVG-Attribute, die aus einer Liste von Zahlen bestehen und sich per SMIL (<animate>) animieren lassen. Dazu gehören etwa rotate bei <text>/<tspan> (SVGTextPositioningElement.rotate), values bei <feColorMatrix>, kernelMatrix bei <feConvolveMatrix> und tableValues bei den Übertragungsfunktionen von <feComponentTransfer>.

Die Schnittstelle hat genau zwei schreibgeschützte Eigenschaften:

baseVal – eine SVGNumberList mit dem Basiswert des Attributs, also dem Wert ohne Animation. Die Liste selbst lässt sich über ihre Methoden (appendItem(), replaceItem(), clear() …) verändern, und die Änderungen werden direkt ins Attribut zurückgeschrieben.
animVal – eine schreibgeschützte SVGNumberList mit dem aktuellen animierten Wert. Läuft keine Animation, enthält sie dieselben Werte wie baseVal.

Man verwendet die Schnittstelle, wenn Zahlenlisten typisiert und ohne String-Parsing gelesen oder verändert werden sollen, z. B. um einzelne Einträge einer Farbmatrix gezielt anzupassen. Die Objekte bekommt man nicht über einen Konstruktor, sondern ausschließlich über die entsprechenden Eigenschaften von SVG-Elementen.

Rückgabewert

Typ

SVGAnimatedNumberList

Beschreibung

Wird von Element-Eigenschaften wie text.rotate oder feColorMatrix.values zurückgegeben; enthält baseVal und animVal (beide vom Typ SVGNumberList).

Beispiele

Rotationswerte eines Textes auslesen

// <svg><text id="t" x="10" y="40" rotate="0 15 30 45">Hallo</text></svg>
const text = document.getElementById('t');
const liste = text.rotate; // SVGAnimatedNumberList

console.log(liste instanceof SVGAnimatedNumberList);
console.log(liste.baseVal.numberOfItems);

const werte = Array.from(
  { length: liste.baseVal.numberOfItems },
  (_, i) => liste.baseVal.getItem(i).value
);
console.log(werte);

true 4 [0, 15, 30, 45]

Farbmatrix eines Filters über baseVal verändern

// <svg id="svg"><filter id="f"><feColorMatrix id="cm" type="saturate" values="1"/></filter></svg>
const svg = document.getElementById('svg');
const matrix = document.getElementById('cm');

const setzeSaettigung = (wert) => {
  const liste = matrix.values.baseVal;
  const zahl = svg.createSVGNumber();
  zahl.value = wert;
  liste.clear();
  liste.appendItem(zahl);
};

setzeSaettigung(0.2);
console.log(matrix.getAttribute('values'));

0.2

Einzelnen Eintrag direkt ändern und animVal vergleichen

const text = document.querySelector('text[rotate]');
const { baseVal, animVal } = text.rotate;

// SVGNumber-Objekte sind live: Änderungen wirken sofort aufs Attribut
baseVal.getItem(0).value = 90;

console.log(text.getAttribute('rotate'));
console.log(animVal.getItem(0).value); // ohne laufende Animation = baseVal

90 15 30 45 90

// Wichtig · Fallstricke

Kein Konstruktor: new SVGAnimatedNumberList() wirft einen TypeError. Neue Einträge erzeugt man über svgElement.createSVGNumber() auf einem <svg>-Element.
animVal ist schreibgeschützt: Versuche, die Liste zu verändern, lösen eine NoModificationAllowedError-DOMException aus. Änderungen immer über baseVal vornehmen.
Browserunterschiede: Die Schnittstelle gibt es in allen modernen Browsern. Ob animVal während einer SMIL-Animation tatsächlich die animierten Werte widerspiegelt, ist aber nicht überall gleich umgesetzt. Für verlässliche Animationen besser CSS oder die Web Animations API verwenden.
Die Eigenschaften baseVal/animVal selbst lassen sich nicht neu zuweisen. Eine Zuweisung wie el.rotate.baseVal = … wird stillschweigend ignoriert (im Strict Mode gibt es einen TypeError).
Fügt man ein SVGNumber ein, das schon zu einer anderen Liste gehört, wird es laut Spezifikation kopiert und nicht verschoben.

Siehe auch

SVGAnimatedNumber SVGAnimatedEnumeration SVGAnimatedLengthList SVGAnimateElement SVGAnimatedBoolean