new DOMMatrix() — Methode · JavaScript-Referenz

Signatur

new DOMMatrix(init)

Beschreibung

Der Konstruktor DOMMatrix() erzeugt eine veränderbare Transformationsmatrix mit 4×4 Werten. Mit ihr lassen sich Verschiebungen, Drehungen, Skalierungen und Scherungen berechnen und verketten, und zwar sowohl für 2D-Inhalte (Canvas, SVG) als auch für 3D-Transformationen in CSS. Die unveränderliche Variante heißt DOMMatrixReadOnly.

Wie die Matrix belegt wird, hängt vom Argument init ab:

Kein Argument: Es entsteht die Einheitsmatrix (isIdentity === true, is2D === true).
String: Ein CSS-Wert für transform, etwa "translate(10px, 20px) rotate(45deg)" oder der Rückgabewert von getComputedStyle(el).transform. Auch "none" ist erlaubt.
Array mit 6 Zahlen: Eine 2D-Matrix in der Reihenfolge [a, b, c, d, e, f], also dieselbe wie bei CSS-matrix() und bei CanvasRenderingContext2D.setTransform().
Array mit 16 Zahlen: Eine 3D-Matrix, spaltenweise angegeben (m11, m12, m13, m14, m21, …, m44), wie bei CSS-matrix3d().

Sinnvoll ist das zum Beispiel, wenn man die aktuelle Transformation eines Elements auslesen und umrechnen will, Mauskoordinaten in das Koordinatensystem eines transformierten Elements oder Canvas zurückrechnen möchte (inverse() plus transformPoint()) oder mehrere Transformationen ohne Stringverkettung zusammenfassen will. Methoden wie translateSelf(), rotateSelf() und scaleSelf() ändern die Matrix direkt. Die Varianten ohne Self geben dagegen eine neue Matrix zurück.

Parameter

Name	Typ	Default	Beschreibung
$init	string \| number[]	Einheitsmatrix	Optionaler Anfangswert. Entweder ein CSS-Transform-String (nur im Fensterkontext) oder ein Array mit genau 6 Werten (2D: `a, b, c, d, e, f`) bzw. genau 16 Werten (3D, spaltenweise).

Rückgabewert

Typ

DOMMatrix

Beschreibung

Ein neues, veränderbares DOMMatrix-Objekt. Bei einem 16er-Array oder einer 3D-Transformation im String ist is2D in der Regel false.

Beispiele

Einheitsmatrix und 2D-Matrix aus einem Array

const identity = new DOMMatrix();
console.log(identity.isIdentity, identity.is2D);

// [a, b, c, d, e, f]: um 50 px nach rechts und 100 px nach unten verschieben
const m = new DOMMatrix([1, 0, 0, 1, 50, 100]);
const p = m.transformPoint(new DOMPoint(10, 10));
console.log(p.x, p.y);

true true 60 110

Matrix aus einem CSS-Transform-String

const m = new DOMMatrix('translate(20px, 10px) scale(2)');
console.log(m.a, m.d, m.e, m.f);
console.log(m.toString());

2 2 20 10 matrix(2, 0, 0, 2, 20, 10)

Aktuelle Transformation eines Elements auslesen und erweitern

const box = document.querySelector('.box');
// Liefert z. B. "matrix(1, 0, 0, 1, 30, 0)" oder "none"
const current = new DOMMatrix(getComputedStyle(box).transform);

// Zusätzlich um 15° drehen, ohne Strings zusammenzusetzen
current.rotateSelf(15);
box.style.transform = current.toString();

Mausposition in Canvas-Koordinaten zurückrechnen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

const view = new DOMMatrix().translateSelf(100, 50).scaleSelf(2);
ctx.setTransform(view);
ctx.fillRect(0, 0, 20, 20);

canvas.addEventListener('click', (e) => {
  const rect = canvas.getBoundingClientRect();
  const screen = new DOMPoint(e.clientX - rect.left, e.clientY - rect.top);
  const world = view.inverse().transformPoint(screen);
  console.log(`Weltkoordinate: ${world.x.toFixed(1)}, ${world.y.toFixed(1)}`);
});

Weltkoordinate: 5.0, 5.0 // bei Klick auf Pixel (110, 60)

// Wichtig · Fallstricke

Strings nur im Fensterkontext: In Web Workern gibt es keinen CSS-Parser. Ein String als init löst dort einen TypeError aus. Im Worker deshalb Arrays oder DOMMatrix.fromFloat64Array() verwenden.
Ungültige Strings und relative Einheiten wie em, % oder vw werfen einen SyntaxError. Erlaubt sind nur absolute Längen wie px sowie Winkeleinheiten (deg, rad, turn).
Falsche Array-Länge: Alles außer genau 6 oder 16 Elementen führt zu einem TypeError.
Reihenfolge bei 16 Werten: Die Werte werden spaltenweise gelesen. Die Verschiebung steht deshalb an Position 13–15 (m41, m42, m43) und nicht in der letzten Spalte, wie man es aus der Mathematik gewohnt ist.
Gleitkomma-Ungenauigkeit: Nach Drehungen stehen oft Werte wie 6.123e-17 statt 0 in der Matrix. Beim Vergleichen deshalb mit einer Toleranz arbeiten.
Eine bestehende Matrix kopiert man besser mit DOMMatrix.fromMatrix() als über den Konstruktor.
Das veraltete WebKitCSSMatrix ist in modernen Browsern nur noch ein Alias für DOMMatrix. In Node.js gibt es DOMMatrix nicht von Haus aus.

Siehe auch

new DOMParser() new Animation() new CSSMathMax() new CSSMathMin() new Comment() new BroadcastChannel() new CSSMathClamp()