SVGGraphicsElement.transform — Eigenschaft · JavaScript-Referenz

Signatur

SVGGraphicsElement.transform

Beschreibung

Die schreibgeschützte Eigenschaft transform von SVGGraphicsElement gibt ein SVGAnimatedTransformList-Objekt zurück. Es bildet das transform-Attribut eines Elements wie <rect>, <g>, <circle> oder <text> ab. Über baseVal erreichst du den statischen Attributwert, über animVal den aktuellen, möglicherweise durch SMIL-Animationen veränderten Wert.

Schreibgeschützt ist nur die Eigenschaft selbst: Du kannst ihr kein neues Objekt zuweisen. Die enthaltene SVGTransformList (baseVal) lässt sich dagegen verändern. Mit appendItem(), insertItemBefore(), removeItem() oder clear() bearbeitest du die Liste, und jedes SVGTransform-Objekt stellt Methoden wie setTranslate(), setRotate() oder setScale() bereit. Jede Änderung wird sofort in das Attribut zurückgeschrieben.

Nützlich ist das vor allem, wenn du Transformationen per Code auswerten oder schrittweise ändern willst, ohne den Attribut-String selbst zu zerlegen. Typische Fälle sind Drag & Drop, Zoomen oder Drehen von SVG-Gruppen. Mit consolidate() fasst du alle Einträge zu einer einzigen Matrix zusammen.

Rückgabewert

Typ

SVGAnimatedTransformList

Beschreibung

Ein Objekt mit den Eigenschaften baseVal (veränderbare SVGTransformList des Attributs) und animVal (schreibgeschützte SVGTransformList mit dem animierten Wert).

Beispiele

Transformationen eines Elements auslesen

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

console.log(list.numberOfItems);
for (const t of Array.from({ length: list.numberOfItems }, (_, i) => list.getItem(i))) {
  // t.type: 2 = TRANSLATE, 4 = ROTATE
  console.log(t.type, t.angle, t.matrix.e, t.matrix.f);
}

2 2 0 20 10 4 45 0 0

Element per Code verschieben (Drag-Grundlage)

const svg = document.querySelector('svg');
const group = svg.querySelector('g');

// Neue Verschiebung erzeugen und an den Anfang der Liste setzen
const move = svg.createSVGTransform();
move.setTranslate(100, 40);
group.transform.baseVal.insertItemBefore(move, 0);

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

translate(100 40)

Alle Transformationen zu einer Matrix zusammenfassen

// <circle id="dot" r="5" transform="translate(10 0) scale(2)"/>
const dot = document.getElementById('dot');
const combined = dot.transform.baseVal.consolidate();

if (combined) {
  const { a, b, c, d, e, f } = combined.matrix;
  console.log([a, b, c, d, e, f]);
}
console.log(dot.transform.baseVal.numberOfItems);

[2, 0, 0, 2, 10, 0] 1

Drehung schrittweise animieren

const svg = document.querySelector('svg');
const rect = svg.querySelector('rect');
const rotation = svg.createSVGTransform();
rect.transform.baseVal.appendItem(rotation);

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

// Wichtig · Fallstricke

Nur das SVG-Attribut: transform.baseVal enthält nur das transform-Attribut. Setzt du die CSS-Eigenschaft transform (etwa per Stylesheet oder element.style.transform), taucht sie hier nicht auf. Das effektive Ergebnis erhältst du über getCTM() bzw. getScreenCTM().
Keine Zuweisung: el.transform = … hat keine Wirkung und wirft im Strict Mode einen TypeError. Bearbeite stattdessen baseVal.
animVal ist schreibgeschützt: Änderungen daran lösen eine DOMException (NoModificationAllowedError) aus.
Leere Liste: Hat das Element kein transform-Attribut, ist numberOfItems gleich 0, und consolidate() liefert null.
appendItem() verschiebt Objekte: Gehört das übergebene SVGTransform schon zu einer anderen Liste, wird es dort entfernt.
Kompatibilität: Wird von allen modernen Browsern unterstützt. SVGTransformList ist nicht iterierbar, deshalb funktioniert for…of nicht direkt. Verwende getItem(i) oder Array.from() mit length/numberOfItems.
Leistung: Wenn du ein vorhandenes SVGTransform-Objekt mit setTranslate() oder setRotate() änderst, ist das bei Animationen schneller, als in jedem Frame den Attribut-String neu zu setzen.

Siehe auch

SVGGraphicsElement.systemLanguage SVGGraphicsElement.requiredExtensions SVGClipPathElement.transform SVGAElement.password SVGGradientElement.href