SVGTransformList.appendItem() — Methode · JavaScript-Referenz

Signatur

SVGTransformList.prototype.appendItem(newItem)

Beschreibung

appendItem() fügt eine neue Transformation (SVGTransform) am Ende einer SVGTransformList ein. Das Attribut transform des Elements wird dabei sofort aktualisiert. An die Liste kommen Sie meist über element.transform.baseVal (bei <linearGradient> über gradientTransform.baseVal, bei <pattern> über patternTransform.baseVal).

Weil SVG Transformationen von rechts nach links auf das Koordinatensystem anwendet, ist die Reihenfolge wichtig: Mit appendItem() hängen Sie die neue Transformation rechts an die bestehende Kette an. So wird sie im lokalen, schon transformierten Koordinatensystem ausgeführt. Ein translate nach einem rotate verschiebt das Element deshalb entlang der gedrehten Achsen.

Neue SVGTransform-Objekte erzeugen Sie mit svgRoot.createSVGTransform() oder svgRoot.createSVGTransformFromMatrix(matrix). Den Typ und die Werte legen Sie danach mit setTranslate(), setRotate(), setScale(), setSkewX(), setSkewY() oder setMatrix() fest. Für die Programmierung ist das oft sauberer, als das Attribut transform als Zeichenkette zusammenzusetzen.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	SVGTransform		Die Transformation, die ans Ende der Liste angehängt werden soll. Gehört das Objekt schon zu einer anderen Liste, wird es je nach Spezifikation und Browser entweder aus der alten Liste entfernt (SVG 1.1) oder als Kopie eingefügt (SVG 2).

Rückgabewert

Typ

SVGTransform

Beschreibung

Das Element, das eingefügt wurde. Nach SVG 2 kann das eine Kopie von newItem sein. Arbeiten Sie deshalb mit dem Rückgabewert weiter, wenn Sie die Transformation später ändern wollen.

Beispiele

Verschiebung an ein Rechteck anhängen

const svg = document.querySelector('svg');
const rect = svg.querySelector('rect');

// Neue Transformation erzeugen und als Verschiebung festlegen
const translate = svg.createSVGTransform();
translate.setTranslate(50, 20);

const list = rect.transform.baseVal;
list.appendItem(translate);

console.log(list.numberOfItems);
console.log(rect.getAttribute('transform'));

1 translate(50 20) // genaue Schreibweise kann je nach Browser abweichen

Mehrere Transformationen verketten (Reihenfolge beachten)

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

const rotate = svg.createSVGTransform();
rotate.setRotate(45, 0, 0);

const move = svg.createSVGTransform();
move.setTranslate(100, 0);

// Erst drehen, dann entlang der gedrehten x-Achse verschieben
list.appendItem(rotate);
list.appendItem(move);

console.log([...Array(list.numberOfItems)].map((_, i) => list.getItem(i).type));

[4, 2] // 4 = SVG_TRANSFORM_ROTATE, 2 = SVG_TRANSFORM_TRANSLATE

Rückgabewert für eine Animation weiterverwenden

const svg = document.querySelector('svg');
const wheel = svg.querySelector('#rad');

// Mit dem Rückgabewert arbeiten, denn er kann eine Kopie sein
const spin = wheel.transform.baseVal.appendItem(svg.createSVGTransform());

let angle = 0;
const tick = () => {
  angle = (angle + 2) % 360;
  spin.setRotate(angle, 50, 50); // um den Mittelpunkt (50|50) drehen
  requestAnimationFrame(tick);
};
requestAnimationFrame(tick);

// Wichtig · Fallstricke

Nur baseVal lässt sich ändern: transform.animVal ist schreibgeschützt. Ein Aufruf dort löst eine DOMException vom Typ NoModificationAllowedError aus.
Kopie oder Original: SVG 1.1 und SVG 2 legen unterschiedlich fest, was mit einem newItem geschieht, das schon in einer anderen Liste steckt. Erzeugen Sie für jede Liste am besten ein eigenes Objekt mit createSVGTransform() und verwenden Sie den Rückgabewert weiter.
Reihenfolge: appendItem() hängt die Transformation rechts an. Sie wirkt damit im schon transformierten Koordinatensystem. Mit insertItemBefore(item, 0) setzen Sie eine Transformation an den Anfang.
Viele Einträge: Wenn Sie wiederholt Transformationen anhängen, wird die Liste immer länger. Mit consolidate() fassen Sie alle Einträge zu einer einzigen Matrix zusammen.
CSS-Transformationen: Setzt CSS eine transform-Eigenschaft, überlagert sie das Attribut transform. Änderungen über appendItem() sind dann nicht zu sehen.
Die Methode wird von allen modernen Browsern unterstützt. Eine gleichwertige appendItem()-Methode gibt es auch bei SVGLengthList, SVGNumberList und SVGPointList.

Siehe auch

SVGTransformList SVGTransform SVGTransformList.insertItemBefore() SVGTransformList.consolidate() SVGSVGElement.createSVGTransform() SVGGraphicsElement.transform new TransformStream()