SVGAnimatedTransformList — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGAnimatedTransformList

Beschreibung

SVGAnimatedTransformList ist die DOM-Schnittstelle für SVG-Attribute, die eine Liste von Transformationen enthalten und animiert werden können. (Die MDN-Kurzbeschreibung spricht von einer „Liste von Zahlen“. Tatsächlich besteht die Liste aus SVGTransform-Objekten wie translate, rotate, scale, skewX, skewY oder matrix.) Du bekommst sie über SVGGraphicsElement.transform, SVGGradientElement.gradientTransform und SVGPatternElement.patternTransform.

Die Schnittstelle hat zwei schreibgeschützte Eigenschaften, die beide eine SVGTransformList liefern:

baseVal: der Grundwert des Attributs. Diese Liste kannst du ändern, zum Beispiel mit appendItem(), insertItemBefore(), removeItem(), clear() oder consolidate(). Jede Änderung wird sofort in das Attribut zurückgeschrieben.
animVal: der aktuelle, gegebenenfalls durch SMIL-Animationen (<animateTransform>) veränderte Wert. Diese Liste kannst du nur lesen.

Die Schnittstelle ist nützlich, wenn du SVG-Transformationen strukturiert und ohne Zeichenkettenverarbeitung auslesen oder ändern willst, etwa für Drag-and-Drop in SVG-Editoren, Zoom und Verschieben (Pan) oder zum Zusammenfassen mehrerer Transformationen zu einer Matrix. Statt getAttribute('transform') zu zerlegen, arbeitest du direkt mit Objekten, die fertige Matrizen enthalten.

Rückgabewert

Typ

SVGAnimatedTransformList

Beschreibung

Das Objekt enthält die Eigenschaften baseVal (änderbare SVGTransformList) und animVal (schreibgeschützte SVGTransformList).

Beispiele

Transformationen eines Elements auslesen

const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
rect.setAttribute('transform', 'translate(10 20) rotate(45)');
svg.append(rect);
document.body.append(svg);

const list = rect.transform; // SVGAnimatedTransformList
console.log(list instanceof SVGAnimatedTransformList);

const { baseVal } = list;
for (let i = 0; i < baseVal.numberOfItems; i++) {
  const t = baseVal.getItem(i);
  // Typ 2 = TRANSLATE, 4 = ROTATE
  console.log(t.type, t.angle, t.matrix.e, t.matrix.f);
}

true 2 0 10 20 4 45 0 0

Transformation hinzufügen (z. B. beim Verschieben)

const svg = document.querySelector('svg');
const shape = svg.querySelector('circle');

const moveBy = (el, dx, dy) => {
  const t = svg.createSVGTransform();
  t.setTranslate(dx, dy);
  el.transform.baseVal.appendItem(t);
  // Liste zu einer einzigen Matrix zusammenfassen
  el.transform.baseVal.consolidate();
};

moveBy(shape, 30, 15);
moveBy(shape, 10, 5);
console.log(shape.getAttribute('transform'));

matrix(1 0 0 1 40 20)

Gradient drehen über gradientTransform

const svg = document.querySelector('svg');
const gradient = svg.querySelector('linearGradient');

const rotateGradient = (deg) => {
  const list = gradient.gradientTransform.baseVal;
  list.clear();
  const t = svg.createSVGTransform();
  t.setRotate(deg, 0.5, 0.5); // um die Mitte der Bounding-Box drehen
  list.appendItem(t);
};

let angle = 0;
setInterval(() => rotateGradient((angle += 5) % 360), 50);

Animierten Wert (animVal) mit dem Grundwert vergleichen

// <rect id="r" width="20" height="20">
//   <animateTransform attributeName="transform" type="rotate"
//     from="0" to="360" dur="4s" repeatCount="indefinite"/>
// </rect>
const rect = document.getElementById('r');

setTimeout(() => {
  const base = rect.transform.baseVal.consolidate();
  const anim = rect.transform.animVal;
  console.log('Basis:', base); // null, weil kein transform-Attribut gesetzt ist
  console.log('Animiert:', anim.numberOfItems > 0 ? anim.getItem(0).angle : 'keine');
}, 1000);

Basis: null Animiert: 90 (ungefähr, je nach Zeitpunkt)

// Wichtig · Fallstricke

Keine Zahlenliste: Anders als die ursprüngliche Kurzbeschreibung nahelegt, enthält die Liste SVGTransform-Objekte und keine Zahlen. Für Zahlenlisten gibt es SVGAnimatedNumberList.
animVal kannst du nur lesen: Schreibende Methoden auf animVal lösen einen NoModificationAllowedError aus. Ändere immer baseVal.
CSS-Transformationen fehlen: Eine per CSS gesetzte Eigenschaft transform (Stylesheet oder style) erscheint weder in baseVal noch in animVal. Für die tatsächlich wirksame Matrix nutzt du getCTM(), getScreenCTM() oder getComputedStyle().
Nur SMIL wird abgebildet: animVal spiegelt nur SMIL-Animationen wie <animateTransform> wider. CSS-Animationen und die Web Animations API tauchen dort nicht auf.
consolidate() gibt bei einer leeren Liste null zurück. Dieser Fall muss vor dem Zugriff auf .matrix abgefangen werden.
Objekte sind live: Jedes SVGTransform-Objekt wirkt direkt auf das Attribut. Wenn du ein Element aus einer Liste in eine andere einfügst, wird es aus der ursprünglichen Liste entfernt.
Kompatibilität: Die Schnittstelle wird in allen modernen Browsern unterstützt. SVG 2 hat einige Details geändert (z. B. length als Alias für numberOfItems), ältere Engines kennen nur numberOfItems.

Siehe auch

SVGAnimateTransformElement SVGAnimatedLengthList SVGAnimatedNumberList SVGTransformList SVGAnimatedAngle