DOMMatrixReadOnly.multiply() — Methode · JavaScript-Referenz

Signatur

DOMMatrixReadOnly.prototype.multiply(otherMatrix)

Beschreibung

multiply() berechnet das Matrixprodukt this × otherMatrix. In MDN wird das oft als „Punktprodukt“ bezeichnet, gemeint ist aber das übliche Produkt zweier 4×4-Matrizen. Das Ergebnis ist eine neue DOMMatrix. Weder die aufrufende Matrix noch das Argument werden verändert. Mit dieser Methode lassen sich mehrere Transformationen wie Verschiebung, Skalierung, Drehung und Scherung zu einer einzigen Matrix zusammenfassen, die man dann z. B. als CSS-transform oder im Canvas verwendet.

Die Reihenfolge ist wichtig: Beim Produkt A.multiply(B) wird ein Punkt zuerst mit B und danach mit A transformiert. Das entspricht der Schreibweise in CSS: transform: A B wendet ebenfalls zuerst die rechte Funktion an. Wer die Operanden vertauscht, bekommt in der Regel ein anderes Ergebnis.

Als Argument ist eine DOMMatrix, eine DOMMatrixReadOnly oder ein einfaches Objekt im Format DOMMatrixInit erlaubt, z. B. { a, b, c, d, e, f } oder { m11 … m44, is2D }. Ohne Argument wird mit der Einheitsmatrix multipliziert, die Methode liefert dann also nur eine Kopie. Ist einer der beiden Operanden eine 3D-Matrix, ist das Ergebnis ebenfalls 3D (is2D === false).

Wenn du eine vorhandene DOMMatrix direkt ändern willst, statt eine neue anzulegen, nimm DOMMatrix.multiplySelf() (rechts anmultiplizieren) oder DOMMatrix.preMultiplySelf() (links anmultiplizieren).

Parameter

Name	Typ	Default	Beschreibung
$otherMatrix	DOMMatrix \| DOMMatrixReadOnly \| DOMMatrixInit	Einheitsmatrix	Die Matrix, mit der von rechts multipliziert wird. Ein einfaches Objekt mit den Feldern `a`–`f` oder `m11`–`m44` ist ebenfalls erlaubt. Fehlende Felder werden mit den Werten der Einheitsmatrix aufgefüllt.

Rückgabewert

Typ

DOMMatrix

Beschreibung

Eine neue, veränderbare DOMMatrix mit dem Produkt this × otherMatrix. Das gilt auch, wenn die Methode auf einer DOMMatrixReadOnly aufgerufen wird.

Beispiele

Verschiebung und Skalierung kombinieren

const translate = new DOMMatrix().translate(100, 50);
const scale = new DOMMatrix().scale(2);

// Zuerst skalieren, dann verschieben
const combined = translate.multiply(scale);
console.log(combined.toString());

// Punkt (10, 10) transformieren
const p = combined.transformPoint(new DOMPoint(10, 10));
console.log(p.x, p.y);

matrix(2, 0, 0, 2, 100, 50) 120 70

Die Reihenfolge ändert das Ergebnis

const translate = new DOMMatrix().translate(100, 50);
const scale = new DOMMatrix().scale(2);

console.log(translate.multiply(scale).toString());
console.log(scale.multiply(translate).toString()); // Verschiebung wird mitskaliert

matrix(2, 0, 0, 2, 100, 50) matrix(2, 0, 0, 2, 200, 100)

Einfaches Objekt als Argument, Ausgangsmatrix bleibt unverändert

const base = new DOMMatrixReadOnly('rotate(90deg)');

// DOMMatrixInit-Objekt statt DOMMatrix
const moved = base.multiply({ e: 10, f: 20 });

console.log(base.e, base.f);   // Original unverändert
console.log(moved instanceof DOMMatrix);
console.log(Math.round(moved.e), Math.round(moved.f));

0 0 true -20 10

Transformation eines Elements um eine weitere ergänzen

const box = document.querySelector('.box');

// Aktuelle berechnete Transformation auslesen
const current = new DOMMatrix(getComputedStyle(box).transform);

// Zusätzlich um 15° drehen, im lokalen Koordinatensystem des Elements
const next = current.multiply(new DOMMatrix().rotate(15));

box.style.transform = next.toString();

// Wichtig · Fallstricke

Reihenfolge: A.multiply(B) wendet zuerst B und dann A auf Punkte an. Soll eine Transformation im Anschluss an die bestehende im globalen Koordinatensystem wirken, schreibst du neu.multiply(bestehend) oder verwendest preMultiplySelf().
Keine Veränderung am Original: Das Ergebnis muss zugewiesen werden. Ein bloßer Aufruf von m.multiply(x) ohne Zuweisung hat keine Wirkung. Wer die Matrix direkt ändern will, nimmt DOMMatrix.multiplySelf().
Ungültiges Argument: Enthält ein DOMMatrixInit-Objekt widersprüchliche Werte (z. B. a: 2 und gleichzeitig m11: 3, oder is2D: true zusammen mit 3D-Werten), wird ein TypeError geworfen.
2D/3D: Ist ein Operand 3D, ist auch das Ergebnis 3D, und toString() liefert dann matrix3d(...) statt matrix(...).
Gleitkomma-Ungenauigkeit: Bei Drehungen entstehen Werte wie 6.123e-17 statt 0. Zum Vergleichen solltest du runden oder eine Toleranz verwenden.
Kompatibilität: In allen aktuellen Browsern und in Web Workers verfügbar. In Node.js gibt es DOMMatrix nicht von Haus aus.

Siehe auch

DOMMatrixReadOnly DOMMatrix DOMMatrix.multiplySelf() DOMMatrix.preMultiplySelf() DOMMatrixReadOnly.translate() DOMMatrixReadOnly.transformPoint() DOMMatrixReadOnly.inverse()