SVGTransformList.insertItemBefore() — Methode · JavaScript-Referenz

Signatur

SVGTransformList.prototype.insertItemBefore(newItem, index)

Beschreibung

Mit insertItemBefore() fügst du ein SVGTransform-Objekt an einer bestimmten Stelle in eine Transformationsliste ein, z. B. in element.transform.baseVal. Das Element an Position index und alle nachfolgenden Elemente rücken dabei um eine Stelle nach hinten.

Die Reihenfolge in der Liste entspricht der Reihenfolge im transform-Attribut. Die Methode ist deshalb nützlich, wenn du eine Transformation vor bestehende Transformationen setzen willst, etwa eine Verschiebung, die im Koordinatensystem des Elternelements wirken soll, während die vorhandene Rotation oder Skalierung erhalten bleibt. Mit appendItem() hängst du dagegen nur am Ende an.

Ist index größer oder gleich numberOfItems, wird das neue Element am Ende der Liste angehängt. Laut SVG 2 wird eine Kopie eingefügt, wenn newItem schon zu einer anderen Liste gehört. Ältere Implementierungen nach SVG 1.1 entfernen das Element stattdessen aus seiner bisherigen Liste. Jede Änderung wirkt sich sofort auf das transform-Attribut im DOM aus.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	SVGTransform		Das einzufügende Transformationsobjekt, meist erzeugt mit `svgRoot.createSVGTransform()` oder `createSVGTransformFromMatrix()`.
$index Pflicht	number		Nullbasierte Position, vor der eingefügt wird. `0` fügt am Anfang ein. Werte ab `numberOfItems` hängen das Element am Ende an.

Rückgabewert

Typ

SVGTransform

Beschreibung

Das tatsächlich eingefügte Element. Nach SVG 2 kann das eine Kopie von newItem sein. Arbeite danach deshalb mit dem Rückgabewert weiter.

Beispiele

Verschiebung vor eine bestehende Rotation setzen

const svg = document.querySelector('svg');
const rect = document.querySelector('#box');
rect.setAttribute('transform', 'rotate(45)');

const list = rect.transform.baseVal;
const move = svg.createSVGTransform();
move.setTranslate(100, 50);

// An Position 0 einfügen, also vor rotate(45)
list.insertItemBefore(move, 0);

console.log(list.numberOfItems);
console.log(list.getItem(0).type === SVGTransform.SVG_TRANSFORM_TRANSLATE);
console.log(rect.getAttribute('transform'));

2 true translate(100 50) rotate(45) (genaues Format je nach Browser)

Skalierung zwischen zwei Transformationen einfügen

const svg = document.querySelector('svg');
const g = document.querySelector('#gruppe');
g.setAttribute('transform', 'translate(20 20) rotate(30)');

const scale = svg.createSVGTransform();
scale.setScale(2, 2);

// Vor Index 1 einfügen, also zwischen translate und rotate
const inserted = g.transform.baseVal.insertItemBefore(scale, 1);

console.log(inserted.matrix.a, inserted.matrix.d);
console.log(g.transform.baseVal.numberOfItems);

2 2 3

Index außerhalb des Bereichs hängt am Ende an

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

const m = svg.createSVGMatrix().skewX(15);
const skew = svg.createSVGTransformFromMatrix(m);

// Liste ist leer, trotzdem kein Fehler: Das Element wird angehängt
list.insertItemBefore(skew, 99);
console.log(list.numberOfItems, list.getItem(0).type);

1 1 (SVG_TRANSFORM_MATRIX)

// Wichtig · Fallstricke

Nur baseVal ist veränderbar: Wenn du transform.animVal änderst, wird ein NoModificationAllowedError ausgelöst.
Reihenfolge beachten: Transformationen werden von links nach rechts verkettet. Eine Verschiebung an Index 0 wirkt im Koordinatensystem des Elternelements, eine Verschiebung am Ende im bereits gedrehten oder skalierten System.
Kopie oder Verschieben: Nach SVG 2 wird eine Kopie eingefügt, wenn das Element schon in einer Liste steckt. Ältere Engines verschieben das Element stattdessen. Um sicherzugehen, nutze den Rückgabewert.
index ist ein unsigned long. Negative Werte werden daher in sehr große Zahlen umgewandelt, und das Element landet am Ende statt am Anfang.
Die Methode wird von allen modernen Browsern unterstützt. Für einfache Fälle ist es oft übersichtlicher, das transform-Attribut per setAttribute() zu setzen oder CSS-transform zu verwenden.

Siehe auch

SVGTransformList SVGTransformList.appendItem() SVGTransformList.replaceItem() SVGTransformList.removeItem() SVGTransform SVGSVGElement.createSVGTransform()