SVGLengthList.replaceItem() — Methode · JavaScript-Referenz

Signatur

SVGLengthList.prototype.replaceItem(newItem, index)

Beschreibung

Mit replaceItem() tauschen Sie einen einzelnen Längenwert in einer SVGLengthList aus. Solche Listen gibt es vor allem bei den Attributen x, y, dx und dy von <text> und <tspan>. Dort legt jeder Wert die Position eines einzelnen Zeichens fest. Die Liste erreichen Sie über element.x.baseVal (bzw. y, dx, dy).

Die Methode ist praktisch, wenn Sie nur einen Wert ändern wollen, ohne die ganze Attributzeichenkette neu zu bauen und mit setAttribute() zu setzen. Das DOM-Attribut wird automatisch angepasst, getAttribute('x') zeigt also sofort den neuen Wert.

Ein neues SVGLength-Objekt legen Sie mit svgElement.createSVGLength() an. Den Wert setzen Sie danach über value, valueAsString oder newValueSpecifiedUnits(). Gehört newItem schon zu einer anderen Liste, fügt der Browser nach SVG 2 eine Kopie ein. Arbeiten Sie deshalb immer mit dem Rückgabewert weiter und nicht mit dem Originalobjekt.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	SVGLength		Das `SVGLength`-Objekt, das das bisherige Element ersetzt. Meist wird es mit `createSVGLength()` erzeugt.
$index Pflicht	number		Nullbasierter Index des Elements, das ersetzt werden soll. Er muss kleiner als `numberOfItems` sein.

Rückgabewert

Typ

SVGLength

Beschreibung

Das Element, das tatsächlich in die Liste eingefügt wurde. Das kann newItem selbst sein oder eine Kopie davon.

Beispiele

x-Position eines einzelnen Zeichens ändern

const svg = document.querySelector('svg');
const text = svg.querySelector('text'); // <text x="10 30 50">ABC</text>

const list = text.x.baseVal;
const len = svg.createSVGLength();
len.valueAsString = '80';

// Zweites Zeichen ("B") auf x=80 verschieben
const inserted = list.replaceItem(len, 1);

console.log(inserted.value);
console.log(text.getAttribute('x'));

80 10 80 50

Einheit gezielt setzen mit newValueSpecifiedUnits()

const svg = document.querySelector('svg');
const tspan = svg.querySelector('tspan'); // <tspan dy="0 0 0">xyz</tspan>

const len = svg.createSVGLength();
len.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_EMS, 0.5);

tspan.dy.baseVal.replaceItem(len, 2); // drittes Zeichen um 0.5em nach unten
console.log(tspan.getAttribute('dy'));

0 0 0.5em

Ungültigen Index abfangen

const svg = document.querySelector('svg');
const text = svg.querySelector('text'); // x="10 30 50"
const list = text.x.baseVal;

const safeReplace = (list, item, index) => {
  try {
    return list.replaceItem(item, index);
  } catch (err) {
    console.warn(`${err.name}: Index ${index} ungültig (Länge ${list.numberOfItems})`);
    return null;
  }
};

const len = svg.createSVGLength();
len.value = 99;
safeReplace(list, len, 5);

IndexSizeError: Index 5 ungültig (Länge 3)

Alle Zeichen gleichmäßig verteilen

const svg = document.querySelector('svg');
const text = svg.querySelector('text'); // x="0 0 0 0"
const list = text.x.baseVal;

for (let i = 0; i < list.numberOfItems; i++) {
  const len = svg.createSVGLength();
  len.value = 20 + i * 25;
  list.replaceItem(len, i);
}
console.log(text.getAttribute('x'));

20 45 70 95

// Wichtig · Fallstricke

IndexSizeError: Liegt index nicht zwischen 0 und numberOfItems - 1, wird eine DOMException vom Typ IndexSizeError ausgelöst. Mit replaceItem() lässt sich die Liste also nicht verlängern. Dafür gibt es appendItem() oder insertItemBefore().
Nur baseVal ist schreibbar: animVal kann nur gelesen werden. Ein Aufruf auf element.x.animVal löst NoModificationAllowedError aus.
Kopie statt Original: Gehört newItem schon zu einer Liste, fügen aktuelle Browser nach SVG 2 eine Kopie ein. Nach der alten SVG-1.1-Regel wurde das Objekt dagegen aus seiner bisherigen Liste entfernt. Verlassen Sie sich deshalb nicht auf die Objektidentität, sondern verwenden Sie den Rückgabewert.
Das ersetzte Element wird von der Liste gelöst. Spätere Änderungen daran wirken sich nicht mehr auf das Attribut aus.
Wenn Sie viele Werte ändern, ist es oft einfacher und schneller, das Attribut einmal komplett mit setAttribute('x', …) zu setzen.
Kompatibilität: wird von allen aktuellen Browsern unterstützt (Chrome, Firefox, Safari, Edge).

Siehe auch

SVGLengthList SVGLengthList.getItem() SVGLengthList.insertItemBefore() SVGLengthList.appendItem() SVGLengthList.removeItem() SVGLength SVGSVGElement.createSVGLength() SVGAnimatedLengthList