SVGGradientElement.gradientTransform — Eigenschaft · JavaScript-Referenz

Signatur

SVGGradientElement.gradientTransform

Beschreibung

Die Eigenschaft gradientTransform der Schnittstelle SVGGradientElement gibt Zugriff auf die Transformationen, die auf das Koordinatensystem eines Farbverlaufs angewendet werden. Sie spiegelt das SVG-Attribut gradientTransform wider, also z. B. rotate(45), scale(2) oder translate(10, 20). So lässt sich ein Verlauf drehen, verzerren oder verschieben, ohne die Geometrie der gefüllten Form selbst zu ändern.

Schreibgeschützt ist nur die Eigenschaft selbst: Man kann ihr kein neues Objekt zuweisen. Das zurückgegebene SVGAnimatedTransformList hat aber zwei Listen: baseVal (der statische, veränderbare Attributwert) und animVal (der aktuelle, ggf. durch SMIL-Animation veränderte Wert, nur lesbar). Über baseVal kann man mit Methoden wie appendItem(), clear(), getItem() oder consolidate() die Transformationen gezielt bearbeiten.

Typische Anwendungsfälle sind interaktive Visualisierungen, bei denen ein Verlauf abhängig von Mausposition oder Zeit rotiert, sowie das Auslesen bestehender Transformationen, etwa um sie in eine Matrix umzurechnen. Neue SVGTransform-Objekte erzeugt man über SVGSVGElement.createSVGTransform() am Wurzel-<svg>-Element.

Rückgabewert

Typ

SVGAnimatedTransformList

Beschreibung

Objekt mit den Eigenschaften baseVal (veränderbare SVGTransformList des Attributwerts) und animVal (schreibgeschützte SVGTransformList des animierten Werts).

Beispiele

Vorhandene Transformationen auslesen

// <svg><defs><linearGradient id="verlauf" gradientTransform="rotate(45) scale(1.5)">...</linearGradient></defs></svg>
const gradient = document.getElementById('verlauf');
const liste = gradient.gradientTransform.baseVal;

for (let i = 0; i < liste.numberOfItems; i++) {
  const t = liste.getItem(i);
  // type: 4 = SVG_TRANSFORM_ROTATE, 3 = SVG_TRANSFORM_SCALE
  console.log(t.type, t.angle, t.matrix.a.toFixed(3));
}

4 45 0.707 3 0 1.500

Verlauf per Skript drehen

const svg = document.querySelector('svg');
const gradient = document.getElementById('verlauf');

const drehung = svg.createSVGTransform();
drehung.setRotate(30, 0.5, 0.5); // 30° um die Mitte (objectBoundingBox)

const liste = gradient.gradientTransform.baseVal;
liste.clear();
liste.appendItem(drehung);

console.log(gradient.getAttribute('gradientTransform'));

rotate(30 0.5 0.5)

Animierter Verlauf mit requestAnimationFrame

const svg = document.querySelector('svg');
const gradient = document.getElementById('verlauf');
const drehung = svg.createSVGTransform();
gradient.gradientTransform.baseVal.initialize(drehung);

const animieren = (zeit) => {
  const winkel = (zeit / 20) % 360;
  // Dasselbe SVGTransform-Objekt ist live mit dem Attribut verbunden
  drehung.setRotate(winkel, 0.5, 0.5);
  requestAnimationFrame(animieren);
};
requestAnimationFrame(animieren);

Alle Transformationen zu einer Matrix zusammenfassen

const gradient = document.getElementById('verlauf');
const liste = gradient.gradientTransform.baseVal;

// consolidate() fasst alle Einträge zu einer Matrix zusammen
const gesamt = liste.consolidate();
if (gesamt) {
  const { a, b, c, d, e, f } = gesamt.matrix;
  console.log(`matrix(${[a, b, c, d, e, f].map(n => n.toFixed(2)).join(' ')})`);
} else {
  console.log('Keine Transformation gesetzt');
}

matrix(1.06 1.06 -1.06 1.06 0.00 0.00)

// Wichtig · Fallstricke

Keine Zuweisung: gradient.gradientTransform = ... wird ignoriert (im Strict Mode TypeError). Änderungen immer über baseVal oder per setAttribute('gradientTransform', '...') vornehmen.
animVal ist schreibgeschützt; Änderungsversuche werfen eine NoModificationAllowedError-DOMException.
Die Wirkung hängt von gradientUnits ab: Bei objectBoundingBox (Standard) beziehen sich Werte wie Drehzentren auf den Bereich 0–1, bei userSpaceOnUse auf Benutzerkoordinaten.
consolidate() ersetzt die Liste durch eine einzige Matrix-Transformation – die ursprünglichen Typen (rotate, scale) gehen dabei verloren.
CSS-transform wirkt nicht auf Verläufe; nur das Attribut gradientTransform transformiert den Farbverlauf.
Kompatibilität: In allen modernen Browsern seit Langem unterstützt. SVG 2 erlaubt zusätzlich die CSS-Transform-Syntax im Attribut, die Unterstützung dafür variiert jedoch.

Siehe auch

SVGGradientElement SVGAnimatedTransformList SVGTransformList SVGTransform SVGSVGElement.createSVGTransform() SVGGradientElement.gradientUnits