SVGNumberList.replaceItem() — Methode · JavaScript-Referenz

Signatur

SVGNumberList.prototype.replaceItem(newItem, index)

Beschreibung

Die Methode replaceItem() der Schnittstelle SVGNumberList ersetzt einen einzelnen Zahlenwert in einer SVG-Zahlenliste. Solche Listen findest du zum Beispiel beim Attribut rotate von <text>/<tspan> (text.rotate.baseVal), bei values von <feColorMatrix> oder bei tableValues von Transferfunktionen (<feFuncR> usw.).

Im Gegensatz dazu, das ganze Attribut per setAttribute() als Zeichenkette neu zu schreiben, änderst du mit replaceItem() gezielt nur einen Eintrag. Das DOM-Attribut wird dabei automatisch angepasst. Das neue Element erzeugst du normalerweise mit SVGSVGElement.createSVGNumber().

Die Methode ist praktisch, wenn du einzelne Werte animieren oder interaktiv anpassen willst, etwa die Drehung eines bestimmten Buchstabens oder einen Koeffizienten einer Farbmatrix. Willst du nur den Zahlenwert ändern, geht das oft noch einfacher über list.getItem(i).value = x.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	SVGNumber		Das `SVGNumber`-Objekt, das eingefügt wird. Du erzeugst es mit `svgElement.createSVGNumber()`.
$index Pflicht	number		Nullbasierte Position des Elements, das ersetzt werden soll. Muss kleiner als `numberOfItems` sein.

Rückgabewert

Typ

SVGNumber

Beschreibung

Das Element, das jetzt in der Liste steht. Nach SVG 2 kann das eine Kopie von newItem sein, wenn newItem schon zu einer anderen Liste gehörte.

Beispiele

Drehung eines einzelnen Buchstabens ersetzen

// <svg id="s"><text id="t" x="10" y="40" rotate="0 0 0 0">SVG!</text></svg>
const svg = document.getElementById('s');
const text = document.getElementById('t');
const list = text.rotate.baseVal; // SVGNumberList

const num = svg.createSVGNumber();
num.value = 45;

// Dritten Buchstaben (Index 2) um 45° drehen
const inserted = list.replaceItem(num, 2);
console.log(inserted.value);
console.log(text.getAttribute('rotate'));

45 0 0 45 0

Koeffizienten einer feColorMatrix per Schieberegler ändern

// <svg id="s"><filter id="f"><feColorMatrix id="m" type="saturate" values="1"/></filter></svg>
// <input id="sat" type="range" min="0" max="1" step="0.05" value="1">
const svg = document.getElementById('s');
const matrix = document.getElementById('m');
const slider = document.getElementById('sat');

slider.addEventListener('input', () => {
  const n = svg.createSVGNumber();
  n.value = Number(slider.value);
  matrix.values.baseVal.replaceItem(n, 0);
  console.log('Sättigung:', matrix.getAttribute('values'));
});

Sättigung: 0.5 (bei Reglerstellung 0,5)

Ungültigen Index abfangen

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

const replaceSafe = (value, index) => {
  const n = svg.createSVGNumber();
  n.value = value;
  try {
    return list.replaceItem(n, index);
  } catch (err) {
    console.warn(`${err.name}: Index ${index} existiert nicht (Länge ${list.numberOfItems})`);
    return null;
  }
};

replaceSafe(90, 99);

IndexSizeError: Index 99 existiert nicht (Länge 4)

// Wichtig · Fallstricke

IndexSizeError: Ist index größer oder gleich numberOfItems, wird eine DOMException geworfen. replaceItem() hängt keine neuen Einträge an, dafür gibt es appendItem().
NoModificationAllowedError: Listen aus animVal sind schreibgeschützt. Ändere immer baseVal.
Kopie oder Verschieben: Nach SVG 1.1 wurde ein newItem, das schon in einer anderen Liste stand, dort entfernt. SVG 2 fügt stattdessen eine Kopie ein. Arbeite deshalb mit dem Rückgabewert und nicht mit dem ursprünglichen Objekt weiter.
Fehlt das Attribut (z. B. kein rotate), ist die Liste leer und jeder Aufruf von replaceItem() scheitert. Setze vorher einen Anfangswert oder nutze appendItem().
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt. SVGNumberList ist eine reine Browser-API und steht in Node.js ohne DOM-Implementierung nicht zur Verfügung.

Siehe auch

SVGNumberList SVGNumberList.getItem() SVGNumberList.insertItemBefore() SVGNumberList.appendItem() SVGNumberList.removeItem() SVGSVGElement.createSVGNumber() SVGNumber