SVGNumberList — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGNumberList

Beschreibung

SVGNumberList steht im SVG-DOM für eine Liste von Zahlen. Das sind SVG-Attribute, die mehrere Zahlen durch Leerzeichen oder Kommas getrennt enthalten. Typische Beispiele sind rotate bei <text> und <tspan>, values bei <feColorMatrix>, kernelMatrix bei <feConvolveMatrix> und tableValues bei den Übertragungsfunktionen von <feComponentTransfer>.

Man erzeugt eine solche Liste nicht selbst, sondern bekommt sie über eine SVGAnimatedNumberList: baseVal ist der veränderbare Grundwert, animVal der schreibgeschützte, gerade animierte Wert. Jedes Element der Liste ist ein SVGNumber mit der Eigenschaft value. Neue Elemente erzeugt man mit SVGSVGElement.createSVGNumber().

Wichtige Mitglieder:

Eigenschaften: length und numberOfItems (beide nur lesbar) geben die Anzahl der Elemente an.
Methoden: clear(), initialize(newItem), getItem(index), insertItemBefore(newItem, index), replaceItem(newItem, index), removeItem(index), appendItem(newItem).
Indexzugriff: In modernen Browsern geht auch list[index], das entspricht getItem(index).

Wenn man die Liste ändert, aktualisiert der Browser das zugehörige Attribut sofort. Umgekehrt spiegelt die Liste Änderungen über setAttribute() wider. So lassen sich Zahlenwerte gezielt ändern, ohne Attribut-Zeichenketten selbst zu zerlegen und neu zusammenzusetzen.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	SVGNumber		Das Element, das mit `initialize()`, `appendItem()`, `insertItemBefore()` oder `replaceItem()` eingefügt wird. Erzeugt wird es mit `svg.createSVGNumber()`.
$index Pflicht	number		Nullbasierte Position für `getItem()`, `insertItemBefore()`, `replaceItem()` und `removeItem()`. Liegt der Index außerhalb des gültigen Bereichs, wird ein `IndexSizeError` geworfen (Ausnahme: `insertItemBefore()` hängt dann ans Ende an).

Rückgabewert

Typ

SVGNumber | void

Beschreibung

getItem(), initialize(), appendItem(), insertItemBefore(), replaceItem() und removeItem() geben das betroffene SVGNumber zurück. clear() gibt undefined zurück.

Beispiele

rotate-Werte 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 list = text.rotate.baseVal; // SVGNumberList

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

4 [0, 15, 30, 45]

Neue Zahl anhängen und Wert ersetzen

const svg = document.querySelector('svg');
const list = document.getElementById('t').rotate.baseVal;

const n = svg.createSVGNumber();
n.value = 60;
list.appendItem(n);

// Ersten Wert direkt ändern
list.getItem(0).value = -10;

console.log(document.getElementById('t').getAttribute('rotate'));

-10 15 30 45 60

Farbmatrix eines Filters auf Graustufen setzen

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

const grau = [
  0.33, 0.33, 0.33, 0, 0,
  0.33, 0.33, 0.33, 0, 0,
  0.33, 0.33, 0.33, 0, 0,
  0,    0,    0,    1, 0
];

list.clear();
for (const v of grau) {
  const num = svg.createSVGNumber();
  num.value = v;
  list.appendItem(num);
}
console.log(list.length);

20

Element entfernen mit Fehlerbehandlung

const list = document.getElementById('t').rotate.baseVal;
try {
  const entfernt = list.removeItem(0);
  console.log('Entfernt:', entfernt.value);
  list.removeItem(99); // ungültiger Index
} catch (e) {
  console.log(e.name);
}

Entfernt: -10 IndexSizeError

// Wichtig · Fallstricke

Kein Konstruktor: new SVGNumberList() wirft einen TypeError. Listen bekommt man nur über baseVal bzw. animVal einer SVGAnimatedNumberList.
animVal ist schreibgeschützt: Jeder Änderungsversuch an animVal wirft einen NoModificationAllowedError. Ändern darf man nur baseVal.
Kein echtes Array: Methoden wie map oder forEach gibt es nicht, und Iterierbarkeit ist nicht überall garantiert. Deshalb besser mit numberOfItems und getItem() in einer Schleife arbeiten oder mit Array.from({ length }) umwandeln.
Einfügen bestehender Elemente: Wenn ein SVGNumber schon zu einer anderen Liste gehört, verhalten sich die Browser je nach Umsetzung von SVG 1.1 oder SVG 2 unterschiedlich: Das Element wird entweder verschoben oder kopiert. Sicherer ist es, immer eine neue Zahl mit createSVGNumber() zu erzeugen.
initialize() leert die Liste und setzt das übergebene Element als einzigen Eintrag. Das wird leicht mit „initialisieren ohne Inhalt verlieren“ verwechselt.
Die Eigenschaft length und der Indexzugriff list[i] kamen erst mit SVG 2. Sehr alte Browser kennen nur numberOfItems und getItem().

Siehe auch

SVGNumber SVGLengthList SVGPointList SVGStringList CSSRuleList CSSValueList