new DOMMatrixReadOnly() — Methode · JavaScript-Referenz

Signatur

new DOMMatrixReadOnly(init)

Beschreibung

Der Konstruktor DOMMatrixReadOnly() erzeugt eine unveränderliche 4×4-Matrix. Mit ihr lassen sich geometrische Transformationen wie Verschiebung, Drehung, Skalierung und Scherung beschreiben und miteinander kombinieren. Ohne Argument entsteht die Einheitsmatrix. Das ist die Transformation, die nichts verändert.

Als Argument kann man eine CSS-Transformationszeichenkette übergeben, zum Beispiel "translate(10px, 20px) rotate(45deg)". Alternativ geht ein Array mit 6 Werten. Diese werden als 2D-Matrix a, b, c, d, e, f gelesen. Ein Array mit 16 Werten wird als 3D-Matrix m11 bis m44 in spaltenweiser Reihenfolge gelesen.

Methoden wie translate(), scale(), rotate(), multiply() oder inverse() verändern die bestehende Matrix nicht. Sie geben jeweils eine neue DOMMatrix zurück. Deshalb eignet sich DOMMatrixReadOnly gut für Werte, die nicht versehentlich verändert werden sollen, zum Beispiel eine Basis-Transformation, die mehrere Codestellen gemeinsam nutzen.

Typische Einsatzgebiete sind das Auswerten von getComputedStyle(el).transform, das Umrechnen von Punkten mit transformPoint() sowie Geometrie-Berechnungen für Canvas, SVG und WebGL.

Parameter

Name	Typ	Default	Beschreibung
$init	string \| number[]	Einheitsmatrix	Startwert: eine CSS-`transform`-Zeichenkette (z. B. `"scale(2) rotate(30deg)"`, auch `"none"`), ein Array mit 6 Zahlen (2D: `a, b, c, d, e, f`) oder ein Array mit 16 Zahlen (3D: `m11`–`m44`, spaltenweise). Andere Array-Längen lösen einen `TypeError` aus.

Rückgabewert

Typ

DOMMatrixReadOnly

Beschreibung

Ein neues, unveränderliches Matrix-Objekt. Über is2D erfährt man, ob es eine reine 2D-Matrix ist, über isIdentity, ob es die Einheitsmatrix ist.

Beispiele

Einheitsmatrix und 2D-Matrix aus einem Array

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

// 2D-Matrix: a, b, c, d, e, f  → Skalierung 2 und Verschiebung (10, 20)
const m = new DOMMatrixReadOnly([2, 0, 0, 2, 10, 20]);
console.log(m.a, m.d, m.e, m.f);
console.log(m.toString());

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

Aus einer CSS-Transformation erzeugen und einen Punkt umrechnen

const m = new DOMMatrixReadOnly('translate(100px, 50px) scale(2)');
const p = m.transformPoint(new DOMPoint(10, 10));
console.log(p.x, p.y);

120 70

Berechnete Transformation eines Elements auslesen

const box = document.querySelector('.box');
box.style.transform = 'rotate(90deg) translateX(40px)';

const { transform } = getComputedStyle(box);
const matrix = new DOMMatrixReadOnly(transform);

// Aus der Matrix die Verschiebung und den Drehwinkel ermitteln
const angle = Math.round(Math.atan2(matrix.b, matrix.a) * 180 / Math.PI);
console.log('Winkel:', angle, 'Verschiebung:', Math.round(matrix.e), Math.round(matrix.f));

Winkel: 90 Verschiebung: 0 40

Unveränderlichkeit: Methoden liefern neue Matrizen

const base = new DOMMatrixReadOnly();
const moved = base.translate(30, 0).rotate(45);

console.log(base.isIdentity);          // Original bleibt unverändert
console.log(moved instanceof DOMMatrix); // Ergebnis ist eine veränderliche DOMMatrix
console.log(Math.round(moved.e));

true true 30

// Wichtig · Fallstricke

Zuweisungen haben keine Wirkung: Die Eigenschaften (a–f, m11–m44) sind reine Leseeigenschaften. Eine Zuweisung wie m.a = 5 wird im Normalmodus stillschweigend ignoriert. Im Strict Mode löst sie einen TypeError aus. Für veränderbare Matrizen gibt es DOMMatrix oder DOMMatrix.fromMatrix(m).
Zeichenketten nur im Fenster-Kontext: CSS-Zeichenketten werden nur in einem Dokument ausgewertet. In Web Workern wirft ein String-Argument einen TypeError. Dort sind nur Arrays erlaubt.
Relative Einheiten sind nicht zulässig: Werte wie % oder em in translate() führen zu einem SyntaxError, weil es keinen Bezugsrahmen gibt. Erlaubt sind absolute Längen wie px und Winkel wie deg, rad und turn.
Nur 6 oder 16 Werte: Arrays anderer Länge lösen einen TypeError aus. Die 16 Werte werden spaltenweise gelesen, also in der Reihenfolge m11, m12, m13, m14, m21, …
Rundungsfehler: Bei Drehungen entstehen oft Werte wie 6.1e-17 statt 0. Vor Vergleichen deshalb runden.
Kompatibilität: Wird von Chrome 61+, Firefox 33+ und Safari 11+ unterstützt. Das alte WebKitCSSMatrix ist heute nur noch ein Alias für DOMMatrix.

Siehe auch

DOMMatrixReadOnly DOMMatrix DOMMatrixReadOnly.prototype.transformPoint() DOMMatrixReadOnly.prototype.multiply() DOMMatrixReadOnly.fromMatrix() DOMPoint getComputedStyle()