SVGTransform.setMatrix() — Methode · JavaScript-Referenz

Signatur

SVGTransform.prototype.setMatrix(matrix)

Beschreibung

setMatrix() ersetzt die aktuelle Transformation eines SVGTransform-Objekts durch die übergebene Matrix. Danach ist type gleich SVGTransform.SVG_TRANSFORM_MATRIX (Wert 1) und angle ist 0. Das gilt auch dann, wenn die Matrix eigentlich nur eine Drehung oder Verschiebung beschreibt.

Die Methode ist nützlich, wenn mehrere Einzeltransformationen (Verschieben, Drehen, Skalieren, Scheren) zu einer Matrix zusammengefasst werden sollen, etwa bei Drag-and-drop, beim Zoomen um einen Punkt oder beim Übernehmen einer Matrix aus getCTM() bzw. getScreenCTM(). Für einfache Fälle gibt es die Methoden setTranslate(), setRotate(), setScale(), setSkewX() und setSkewY().

Die Werte der Matrix werden kopiert. Wenn man das übergebene Matrix-Objekt danach ändert, bleibt die Transformation gleich. Gehört das SVGTransform zu einer SVGTransformList eines Elements (z. B. element.transform.baseVal), wird das transform-Attribut sofort aktualisiert.

Parameter

Name	Typ	Default	Beschreibung
$matrix Pflicht	SVGMatrix \| DOMMatrix \| DOMMatrix2DInit		Die neue 2D-Transformationsmatrix mit den Werten `a`–`f`. Nach SVG 2 ist jedes Objekt mit `a`, `b`, `c`, `d`, `e`, `f` (bzw. `m11`…`m42`) erlaubt. Ältere Implementierungen erwarten ein `SVGMatrix`.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Das SVGTransform-Objekt wird direkt verändert.

Beispiele

Verschiebungsmatrix an ein Rechteck anhängen

const svgNS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(svgNS, 'svg');
const rect = document.createElementNS(svgNS, 'rect');
rect.setAttribute('width', '50');
rect.setAttribute('height', '50');
svg.append(rect);
document.body.append(svg);

// Matrix für eine Verschiebung um (30, 20)
const m = svg.createSVGMatrix();
m.e = 30;
m.f = 20;

const t = svg.createSVGTransform();
t.setMatrix(m);
rect.transform.baseVal.appendItem(t);

console.log(t.type === SVGTransform.SVG_TRANSFORM_MATRIX);
console.log(rect.getAttribute('transform'));

true matrix(1 0 0 1 30 20)

Um einen Mittelpunkt drehen – als eine Matrix

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

const cx = 100, cy = 100;
// Verschieben, drehen, zurückverschieben – zu einer Matrix verkettet
const m = svg.createSVGMatrix()
  .translate(cx, cy)
  .rotate(45)
  .translate(-cx, -cy);

const t = svg.createSVGTransform();
t.setMatrix(m);
shape.transform.baseVal.initialize(t); // ersetzt alle bisherigen Transformationen

console.log(t.type, t.angle); // Typ MATRIX, Winkel geht verloren

1 0

Bestehende rotate()-Transformation zusätzlich skalieren

const rect = document.querySelector('rect');
rect.setAttribute('transform', 'rotate(30)');

const t = rect.transform.baseVal.getItem(0);
console.log(t.type); // 4 = SVG_TRANSFORM_ROTATE

// Die Werte werden kopiert, deshalb darf t.matrix selbst als Grundlage dienen
t.setMatrix(t.matrix.scale(2));

console.log(t.type); // 1 = SVG_TRANSFORM_MATRIX
console.log(rect.getAttribute('transform').startsWith('matrix('));

4 1 true

// Wichtig · Fallstricke

Informationsverlust: Nach setMatrix() ist angle immer 0 und type immer SVG_TRANSFORM_MATRIX. Der ursprüngliche Drehwinkel oder Skalierungsfaktor lässt sich danach nicht mehr direkt auslesen.
Kopie statt Referenz: Wenn man das übergebene Matrix-Objekt später ändert, bleibt die Transformation gleich. Man muss setMatrix() dann erneut aufrufen.
Schreibgeschützte Objekte: Auf Transformationen aus animVal wirft der Aufruf einen NoModificationAllowedError. Nur baseVal lässt sich ändern.
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt. Ob ein DOMMatrix oder ein einfaches Objekt wie {a, b, c, d, e, f} akzeptiert wird (SVG 2), hängt vom Browser ab. Am sichersten ist svg.createSVGMatrix(). SVGMatrix gilt allerdings als veraltet und ist in SVG 2 ein Alias für DOMMatrix.
Es werden nur 2D-Anteile verwendet. 3D-Werte eines DOMMatrix werden ignoriert oder führen zu einem Fehler.

Siehe auch

SVGTransform SVGTransform.setTranslate() SVGTransform.setRotate() SVGTransform.setScale() SVGTransformList SVGSVGElement.createSVGMatrix()