DOMMatrix — Schnittstelle · JavaScript-Referenz

Signatur

interface DOMMatrix extends DOMMatrixReadOnly

Beschreibung

DOMMatrix stellt eine 4×4-Transformationsmatrix dar und ist die veränderbare Variante von DOMMatrixReadOnly. Die Schnittstelle ersetzt die veralteten Typen WebKitCSSMatrix und SVGMatrix. Ein DOMMatrix-Objekt lässt sich aus einem CSS-Transform-String, einem Array mit 6 Werten (2D) oder 16 Werten (3D) oder aus einer anderen Matrix erzeugen.

Für 2D-Transformationen gibt es die Kurz-Eigenschaften a bis f (entsprechend matrix(a, b, c, d, e, f) in CSS). Alle 16 Werte sind über m11 bis m44 erreichbar. Die schreibgeschützte Eigenschaft is2D gibt an, ob die Matrix als 2D-Matrix gilt, isIdentity, ob sie der Einheitsmatrix entspricht.

Wichtig ist der Unterschied zwischen zwei Methodenfamilien:

Nicht verändernde Methoden (von DOMMatrixReadOnly geerbt), z. B. translate(), rotate(), scale(), multiply(), inverse(), geben eine neue Matrix zurück.
Verändernde Methoden mit dem Suffix Self, z. B. translateSelf(), rotateSelf(), scaleSelf(), multiplySelf(), preMultiplySelf(), invertSelf() und setMatrixValue(), ändern die Matrix direkt und geben sie für Verkettungen zurück.

Typische Einsatzgebiete sind das Auslesen und Umrechnen berechneter CSS-Transformationen (getComputedStyle(el).transform), Canvas-Transformationen über CanvasRenderingContext2D.setTransform() und getTransform(), Hit-Tests durch Rücktransformation von Mauskoordinaten sowie das Transformieren von Punkten mit transformPoint().

Parameter

Name	Typ	Default	Beschreibung
$init	string \| number[] \| DOMMatrix \| DOMMatrixReadOnly	Einheitsmatrix	Konstruktor-Argument von `new DOMMatrix(init)`: ein CSS-Transform-String (z. B. `"translate(10px, 20px) rotate(45deg)"`, nur im Hauptthread mit Dokument), ein Array mit genau 6 Werten (2D: `a, b, c, d, e, f`) oder 16 Werten (3D, spaltenweise `m11…m44`). Andere Array-Längen werfen einen `TypeError`.

Beispiele

Matrix erzeugen und verkettet transformieren

// Einheitsmatrix erzeugen und direkt verändern
const m = new DOMMatrix();
m.translateSelf(100, 50).rotateSelf(90).scaleSelf(2);

console.log(m.is2D);
console.log(m.toString());

// Aus 2D-Array erzeugen
const m2 = new DOMMatrix([1, 0, 0, 1, 30, 40]);
console.log(m2.e, m2.f);

true matrix(0, 2, -2, 0, 100, 50) 30 40

Punkt transformieren und zurückrechnen

const matrix = new DOMMatrix()
  .translate(200, 100)
  .rotate(45);

const p = new DOMPoint(10, 0);
const transformiert = p.matrixTransform(matrix);
console.log(transformiert.x.toFixed(2), transformiert.y.toFixed(2));

// Mit der Inversen zurück in das Ursprungssystem
const zurueck = transformiert.matrixTransform(matrix.inverse());
console.log(zurueck.x.toFixed(2), zurueck.y.toFixed(2));

207.07 107.07 10.00 0.00

Berechnete CSS-Transformation eines Elements auslesen

const box = document.querySelector('.box');
box.style.transform = 'translate(40px, 20px) scale(1.5)';

const { transform } = getComputedStyle(box);
const m = new DOMMatrix(transform === 'none' ? undefined : transform);

console.log(`Verschiebung: ${m.e}px / ${m.f}px`);
console.log(`Skalierung: ${m.a}`);

Verschiebung: 40px / 20px Skalierung: 1.5

Mausklick in Canvas-Koordinaten umrechnen (Hit-Test)

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

ctx.setTransform(new DOMMatrix().translate(150, 75).rotate(30).scale(2));
ctx.fillRect(-10, -10, 20, 20);

canvas.addEventListener('click', (e) => {
  const rect = canvas.getBoundingClientRect();
  const inverse = ctx.getTransform().invertSelf();
  const local = new DOMPoint(e.clientX - rect.left, e.clientY - rect.top)
    .matrixTransform(inverse);
  const getroffen = Math.abs(local.x) <= 10 && Math.abs(local.y) <= 10;
  console.log(getroffen ? 'Quadrat getroffen' : 'daneben');
});

// Wichtig · Fallstricke

Verändernd oder nicht: rotate() liefert eine neue Matrix, rotateSelf() ändert das Objekt selbst. Wer m.translate(10, 0); ohne Zuweisung aufruft, verliert das Ergebnis. Das ist ein häufiger Fehler.
Reihenfolge der Multiplikation: a.multiply(b) berechnet a × b. Verkettete Transformationen wirken daher wie in CSS von rechts nach links auf den Punkt. preMultiplySelf() multipliziert von links.
Winkel werden bei rotate()/rotateSelf() in Grad angegeben, nicht im Bogenmaß (anders als bei ctx.rotate()).
2D-Status: Sobald 3D-Operationen (z. B. rotate(x, y, z) mit x/y-Anteil oder translate(x, y, z) mit z ≠ 0) angewendet werden, wird is2D dauerhaft false. toString() liefert dann matrix3d(...).
CSS-Strings werden im Konstruktor nur in Umgebungen mit Dokument geparst. In Web Workern wirft ein String einen TypeError. Relative Einheiten wie % oder em sind nicht erlaubt (SyntaxError). Der Wert \"none\" ist nicht zulässig, bitte vorher prüfen.
Nicht invertierbare Matrizen (Determinante 0, z. B. scale(0)): inverse() liefert eine Matrix aus NaN-Werten, ohne einen Fehler zu werfen.
Kompatibilität: In allen modernen Browsern und in Node.js ohne DOM nicht global verfügbar. WebKitCSSMatrix ist in Browsern ein Alias, sollte aber nicht mehr verwendet werden. SVGMatrix gilt als veraltet.

Siehe auch

DOMMatrixReadOnly DOMPoint DOMError DOMParser Animation