Signatur
Beschreibung
Die Eigenschaft transform der Schnittstelle SVGClipPathElement spiegelt das transform-Attribut eines <clipPath>-Elements wider. Sie liefert ein SVGAnimatedTransformList-Objekt, das die Liste aller Transformationen enthält (z. B. translate, rotate, scale, matrix), die auf den Inhalt des Clipping-Pfads angewendet werden.
Die Eigenschaft selbst ist schreibgeschützt: Du kannst ihr kein neues Objekt zuweisen. Die enthaltene Liste ist jedoch veränderbar. Über transform.baseVal (eine SVGTransformList) lassen sich Transformationen lesen, hinzufügen, ersetzen, entfernen oder zu einer einzigen Matrix zusammenfassen. transform.animVal enthält den aktuell animierten Wert (z. B. während einer SMIL-Animation mit <animateTransform>) und ist nur lesbar.
Typische Einsatzfälle sind das programmatische Verschieben, Drehen oder Skalieren einer Clipping-Maske – etwa für Enthüllungs-Effekte, Spotlight-Animationen oder interaktive Ausschnitte, die dem Mauszeiger folgen –, ohne die einzelnen Formen im <clipPath> anfassen zu müssen. Da SVGClipPathElement nicht von SVGGraphicsElement erbt, definiert die Schnittstelle diese Eigenschaft selbst.
Rückgabewert
baseVal (veränderbare SVGTransformList des Attributwerts) und animVal (schreibgeschützte, aktuell animierte SVGTransformList).Beispiele
Transformationen eines clipPath auslesen
const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
const clip = document.createElementNS(SVG_NS, 'clipPath');
clip.id = 'ausschnitt';
clip.setAttribute('transform', 'translate(10 20) rotate(45)');
svg.append(clip);
document.body.append(svg);
const liste = clip.transform.baseVal;
console.log('Anzahl:', liste.numberOfItems);
for (let i = 0; i < liste.numberOfItems; i++) {
const t = liste.getItem(i);
// type: 2 = TRANSLATE, 3 = SCALE, 4 = ROTATE
console.log(`Typ ${t.type}, e=${t.matrix.e}, f=${t.matrix.f}, Winkel=${t.angle}`);
}Clipping-Maske folgt dem Mauszeiger
// Voraussetzung im HTML:
// <svg id="bild" width="400" height="300">
// <clipPath id="spot"><circle r="50" /></clipPath>
// <image href="foto.jpg" width="400" height="300" clip-path="url(#spot)" />
// </svg>
const svg = document.querySelector('#bild');
const clip = svg.querySelector('#spot');
// Eine Translate-Transformation anlegen und einmalig einhängen
const verschiebung = svg.createSVGTransform();
clip.transform.baseVal.initialize(verschiebung);
svg.addEventListener('pointermove', (event) => {
const rect = svg.getBoundingClientRect();
verschiebung.setTranslate(event.clientX - rect.left, event.clientY - rect.top);
});
console.log(clip.getAttribute('transform'));Mehrere Transformationen zu einer Matrix zusammenfassen
const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
const clip = document.createElementNS(SVG_NS, 'clipPath');
svg.append(clip);
document.body.append(svg);
const liste = clip.transform.baseVal;
const skalierung = svg.createSVGTransform();
skalierung.setScale(2, 2);
const drehung = svg.createSVGTransform();
drehung.setRotate(90, 0, 0);
liste.appendItem(skalierung);
liste.appendItem(drehung);
console.log('Vorher:', liste.numberOfItems);
const gesamt = liste.consolidate();
console.log('Nachher:', liste.numberOfItems, 'Typ:', gesamt.type);
const { a, b, c, d } = gesamt.matrix;
console.log([a, b, c, d].map((n) => Math.round(n)));// Wichtig · Fallstricke
- Keine Zuweisung möglich:
clip.transform = …hat keine Wirkung (im Strict Mode gibt es einenTypeError). Ändere stattdessenclip.transform.baseValoder setze das Attribut mitsetAttribute('transform', …). - Live-Verbindung:
baseValist live. Änderungen an der Liste oder an einzelnenSVGTransform-Objekten schreiben sofort ins Attribut zurück und umgekehrt. Ein Objekt, das du mitappendItem()einer Liste hinzufügst, wird aus einer anderen Liste entfernt, falls es dort bereits war. - Neue Transformationen legst du mit
SVGSVGElement.createSVGTransform()auf dem Wurzel-<svg>an. Das<clipPath>-Element selbst hat diese Methode nicht. clipPathUnitsbeachten: BeiclipPathUnits="objectBoundingBox"wird die Transformation im Koordinatensystem der Begrenzungsbox (0–1) angewendet. Eintranslate(10 20)verschiebt dann um das Zehn- bzw. Zwanzigfache der Box-Größe.- CSS-Eigenschaft
transform: In SVG 2 isttransformauch eine Präsentationseigenschaft. Per CSS gesetzte Transformationen tauchen inbaseValnicht auf, weil dort nur der Attributwert abgebildet wird. animValist schreibgeschützt. Schreibzugriffe darauf lösen eineNoModificationAllowedError-Ausnahme aus.- Kompatibilität: Wird von allen modernen Browsern (Chrome, Edge, Firefox, Safari) seit Langem unterstützt.