SVGTransformList.replaceItem() — Methode · JavaScript-Referenz

Signatur

SVGTransformList.prototype.replaceItem(newItem, index)

Beschreibung

replaceItem() tauscht in einer SVGTransformList, also der Liste der Transformationen im transform-Attribut eines SVG-Elements, genau einen Eintrag aus. Die übrigen Transformationen bleiben dabei in Reihenfolge und Wert erhalten. So lässt sich z. B. nur die Drehung einer Kette wie translate(50 50) rotate(0) scale(2) ändern, ohne den Attribut-String neu zusammenzubauen.

Zugriff auf die veränderbare Liste bekommst du über element.transform.baseVal. Ein neues SVGTransform erzeugst du mit svgRoot.createSVGTransform() und setzt es danach mit setTranslate(), setRotate(), setScale(), setSkewX()/setSkewY() oder setMatrix(). Alternativ erzeugt createSVGTransformFromMatrix() direkt ein Objekt aus einer Matrix.

Jede Änderung an baseVal wird sofort ins transform-Attribut übernommen und die Darstellung aktualisiert. Die Methode eignet sich deshalb für interaktive Manipulationen (Ziehen, Drehen, Zoomen), bei denen immer wieder einzelne Transformationsschritte ausgetauscht werden.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	SVGTransform		Das Transformationsobjekt, das an die Stelle des alten Eintrags tritt. Gehört es schon zu einer anderen Liste, fügt der Browser je nach Spezifikationsstand (SVG 1.1 oder SVG 2) entweder das Objekt selbst ein (und entfernt es aus der alten Liste) oder eine Kopie davon.
$index Pflicht	number		Nullbasierte Position des Eintrags, der ersetzt werden soll. Muss kleiner als `numberOfItems` sein.

Rückgabewert

Typ

SVGTransform

Beschreibung

Das eingefügte Element. Wurde eine Kopie eingefügt (SVG-2-Verhalten), ist es diese Kopie und nicht das übergebene Objekt. Weitere Änderungen solltest du daher am Rückgabewert vornehmen.

Beispiele

Drehung in einer Transformationskette austauschen

// <svg id="stage"><rect id="box" width="40" height="40" transform="translate(50 50) rotate(0) scale(2)"/></svg>
const svg = document.getElementById('stage');
const box = document.getElementById('box');
const list = box.transform.baseVal;

const rotation = svg.createSVGTransform();
rotation.setRotate(45, 20, 20); // 45° um den Mittelpunkt

list.replaceItem(rotation, 1); // Index 1 = rotate(0)
console.log(box.getAttribute('transform'));

translate(50 50) rotate(45 20 20) scale(2)

Eintrag durch eine Matrix ersetzen

const svg = document.querySelector('svg');
const shape = svg.querySelector('rect');
const list = shape.transform.baseVal;

if (list.numberOfItems === 0) {
  list.appendItem(svg.createSVGTransform()); // Platzhalter anlegen
}

const matrix = new DOMMatrix().translate(10, 20).scale(1.5);
const t = svg.createSVGTransformFromMatrix(matrix);
const inserted = list.replaceItem(t, 0);

console.log(inserted.type === SVGTransform.SVG_TRANSFORM_MATRIX);

true

Interaktive Drehung per Mausrad

const svg = document.querySelector('svg');
const knob = document.getElementById('knob');
knob.setAttribute('transform', 'translate(100 100) rotate(0)');

let angle = 0;
knob.addEventListener('wheel', (event) => {
  event.preventDefault();
  angle = (angle + Math.sign(event.deltaY) * 10) % 360;

  const rot = svg.createSVGTransform();
  rot.setRotate(angle, 0, 0);
  knob.transform.baseVal.replaceItem(rot, 1);
}, { passive: false });

Fehlerbehandlung bei ungültigem Index

const svg = document.querySelector('svg');
const list = svg.querySelector('rect').transform.baseVal;

try {
  list.replaceItem(svg.createSVGTransform(), list.numberOfItems);
} catch (err) {
  console.log(err.name);
}

IndexSizeError

// Wichtig · Fallstricke

Index außerhalb des Bereichs: Ist index größer oder gleich numberOfItems, wird eine IndexSizeError-DOMException ausgelöst. Mit replaceItem() kann man also nichts anhängen, dafür gibt es appendItem().
Nur baseVal ist veränderbar: transform.animVal ist schreibgeschützt. Ein Aufruf darauf löst NoModificationAllowedError aus.
Objektidentität: SVG 1.1 verschiebt ein Objekt, das schon in einer anderen Liste steckt, in die neue Liste. SVG 2 fügt stattdessen eine Kopie ein. Arbeite deshalb mit dem Rückgabewert statt mit der ursprünglichen Referenz, dann verhält sich dein Code in allen Browsern gleich.
Leistung: Schreibe bei häufigen Aktualisierungen (z. B. in requestAnimationFrame) lieber direkt über list.getItem(i).setRotate(...) in ein bestehendes Objekt, statt jedes Mal ein neues SVGTransform zu erzeugen.
Die Methode wird in allen modernen Browsern unterstützt. CSS-Transformationen (style.transform) werden von dieser Liste nicht erfasst.

Siehe auch

SVGTransformList SVGTransformList.getItem() SVGTransformList.appendItem() SVGTransformList.insertItemBefore() SVGTransformList.removeItem() SVGTransform SVGSVGElement.createSVGTransform()