SVGTransformList — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGTransformList

Beschreibung

SVGTransformList ist die Objektdarstellung einer Liste von Transformationen, wie sie im transform-Attribut (bzw. gradientTransform oder patternTransform) steht, z. B. translate(10 20) rotate(45). Man erhält sie nicht über einen Konstruktor, sondern über element.transform.baseVal (änderbar) oder element.transform.animVal (nur lesbar, aktueller animierter Wert). Beide gehören zu einem SVGAnimatedTransformList.

Die Liste ist live: Wenn Sie Einträge ändern, einfügen oder entfernen, wird das zugehörige Attribut sofort aktualisiert – und umgekehrt. So lassen sich Transformationen gezielt ändern, ohne Strings zu parsen oder neu zusammenzusetzen, etwa bei Drag-and-Drop, Zoom oder Rotation in interaktiven Grafiken.

Wichtige Mitglieder:

length / numberOfItems – Anzahl der Einträge.
getItem(index) bzw. Indexzugriff list[index] – liefert ein SVGTransform.
appendItem(newItem), insertItemBefore(newItem, index), replaceItem(newItem, index), removeItem(index) – Liste bearbeiten.
clear() und initialize(newItem) – Liste leeren bzw. auf genau einen Eintrag setzen.
createSVGTransformFromMatrix(matrix) – erzeugt ein SVGTransform vom Typ Matrix.
consolidate() – multipliziert alle Einträge zu einer einzigen Matrix-Transformation zusammen und gibt sie zurück (oder null bei leerer Liste).

Neue SVGTransform-Objekte erzeugt man mit svgRoot.createSVGTransform() und konfiguriert sie danach über setTranslate(), setRotate(), setScale() usw.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nullbasierter Index für `getItem()`, `insertItemBefore()`, `replaceItem()` und `removeItem()`. Außerhalb des Bereichs wird ein `IndexSizeError` ausgelöst (bei `insertItemBefore()` wird ein zu großer Index als Anhängen interpretiert).
$newItem Pflicht	SVGTransform		Einzufügendes Transformationsobjekt für `appendItem()`, `insertItemBefore()`, `replaceItem()` und `initialize()`.
$matrix	DOMMatrix2DInit \| SVGMatrix	Einheitsmatrix	Nur für `createSVGTransformFromMatrix()`: Matrix mit den Werten `a`–`f`, aus der ein Matrix-Transform erzeugt wird.

Rückgabewert

Typ

SVGTransformList

Beschreibung

Wird über SVGAnimatedTransformList.baseVal bzw. animVal bereitgestellt. Die Methoden liefern meist das eingefügte/entfernte SVGTransform; consolidate() liefert SVGTransform | null, clear() liefert undefined.

Beispiele

Transformationen eines Elements auslesen

// <svg id="stage"><rect id="box" width="50" height="50" transform="translate(20 30) rotate(45)"/></svg>
const box = document.getElementById('box');
const list = box.transform.baseVal; // SVGTransformList

const typeNames = {
  [SVGTransform.SVG_TRANSFORM_TRANSLATE]: 'translate',
  [SVGTransform.SVG_TRANSFORM_ROTATE]: 'rotate',
  [SVGTransform.SVG_TRANSFORM_SCALE]: 'scale',
  [SVGTransform.SVG_TRANSFORM_MATRIX]: 'matrix'
};

console.log('Anzahl:', list.numberOfItems);
for (let i = 0; i < list.numberOfItems; i++) {
  const t = list.getItem(i);
  console.log(i, typeNames[t.type] ?? t.type, t.matrix.e, t.matrix.f);
}

Anzahl: 2 0 translate 20 30 1 rotate 0 0

Rotation anhängen und Verschiebung ersetzen

const svg = document.getElementById('stage');
const box = document.getElementById('box');
const list = box.transform.baseVal;

// Neue Rotation um den Mittelpunkt des Rechtecks anhängen
const rot = svg.createSVGTransform();
rot.setRotate(15, 25, 25);
list.appendItem(rot);

// Erste Transformation (translate) durch eine neue ersetzen
const move = svg.createSVGTransform();
move.setTranslate(100, 50);
list.replaceItem(move, 0);

console.log(box.getAttribute('transform'));

translate(100 50) rotate(45) rotate(15 25 25)

Drag-and-Drop: alles zu einer Matrix zusammenfassen

const svg = document.getElementById('stage');
const box = document.getElementById('box');

const getTranslate = (el) => {
  const list = el.transform.baseVal;
  // consolidate() reduziert die Liste auf einen einzigen Matrix-Eintrag
  const t = list.consolidate() ?? svg.createSVGTransform();
  if (list.numberOfItems === 0) list.appendItem(t);
  // Vor die Matrix eine eigene Verschiebung setzen, die wir beim Ziehen ändern
  const move = svg.createSVGTransform();
  move.setTranslate(0, 0);
  list.insertItemBefore(move, 0);
  return list.getItem(0);
};

let drag = null;
box.addEventListener('pointerdown', (e) => {
  const t = getTranslate(box);
  drag = { t, startX: e.clientX, startY: e.clientY };
  box.setPointerCapture(e.pointerId);
});
box.addEventListener('pointermove', (e) => {
  if (!drag) return;
  drag.t.setTranslate(e.clientX - drag.startX, e.clientY - drag.startY);
});
box.addEventListener('pointerup', () => { drag = null; });

Siehe auch

SVGTransform RTCTransformEvent SVGStringList CSSTransformValue DataTransferItemList