DOMMatrixReadOnly — Schnittstelle · JavaScript-Referenz

Signatur

interface DOMMatrixReadOnly

Beschreibung

DOMMatrixReadOnly ist die unveränderliche Basis-Schnittstelle der Geometry-API. Eine Instanz beschreibt eine homogene 4×4-Transformationsmatrix mit den Komponenten m11 bis m44. Für 2D-Transformationen gibt es die Kurzformen a, b, c, d, e, f. Diese entsprechen m11, m12, m21, m22, m41 und m42. Die Eigenschaft is2D zeigt an, ob die Matrix als reine 2D-Matrix behandelt wird. isIdentity prüft, ob es sich um die Einheitsmatrix handelt.

Alle Transformationsmethoden verändern die Ausgangsmatrix nicht. Das gilt für translate(), scale(), scale3d(), rotate(), rotateAxisAngle(), rotateFromVector(), skewX(), skewY(), multiply(), flipX(), flipY() und inverse(). Jede dieser Methoden gibt eine neue DOMMatrix zurück. Dazu kommen transformPoint() zum Umrechnen von Punkten, toFloat32Array() und toFloat64Array() zum Export der Werte in Spaltenreihenfolge, toJSON() sowie toString(). toString() erzeugt einen CSS-tauglichen String wie matrix(…) oder matrix3d(…).

Einsatzgebiete sind unter anderem:

Auslesen und Zerlegen berechneter CSS-Transformationen, zum Beispiel aus getComputedStyle(el).transform
Umrechnen von Koordinaten zwischen Bezugssystemen, etwa bei Maus-Hit-Tests in transformierten Elementen oder in Canvas-Szenen
Unveränderliche Konfigurationswerte, die nicht versehentlich geändert werden dürfen

Für Matrizen, die an Ort und Stelle verändert werden sollen, gibt es die abgeleitete Schnittstelle DOMMatrix mit den Methoden …Self().

Parameter

Name	Typ	Default	Beschreibung
$init	string \| number[]	Einheitsmatrix	Konstruktor-Argument von `new DOMMatrixReadOnly(init)`. Möglich sind ein CSS-Transform-String wie `"rotate(45deg) translate(10px, 0)"`, ein Array mit 6 Werten (2D: `a, b, c, d, e, f`) oder ein Array mit 16 Werten (3D, in Spaltenreihenfolge). Ein String wird nur im Hauptthread akzeptiert, nicht in Workern.

Rückgabewert

Typ

DOMMatrixReadOnly

Beschreibung

Der Konstruktor liefert eine neue, unveränderliche Matrix. Die Transformationsmethoden der Instanz geben jeweils eine neue DOMMatrix zurück.

Beispiele

Instanziierung und Eigenschaften lesen

// 2D-Matrix aus sechs Werten: a, b, c, d, e, f
const m = new DOMMatrixReadOnly([1, 0, 0, 1, 50, 20]);

console.log(m.is2D);       // true
console.log(m.isIdentity); // false
console.log(m.e, m.f);     // Verschiebung in x/y
console.log(m.toString());

// Ohne Argument entsteht die Einheitsmatrix
const id = DOMMatrixReadOnly.fromMatrix();
console.log(id.isIdentity);

true false 50 20 matrix(1, 0, 0, 1, 50, 20) true

Unveränderliche Transformationen verketten

const base = new DOMMatrixReadOnly('translate(100px, 0)');

// Jede Methode liefert eine NEUE DOMMatrix, base bleibt unverändert
const rotated = base.rotate(90).scale(2);

console.log(base.toString());
console.log(rotated instanceof DOMMatrix);
console.log(rotated.a.toFixed(2), rotated.b.toFixed(2));

matrix(1, 0, 0, 1, 100, 0) true 0.00 2.00

Mausposition in lokale Koordinaten eines transformierten Elements umrechnen

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

box.addEventListener('click', (event) => {
  const rect = box.getBoundingClientRect();
  const css = getComputedStyle(box).transform; // z. B. "matrix(...)" oder "none"
  const matrix = new DOMMatrixReadOnly(css === 'none' ? undefined : css);

  // Umkehrmatrix: Bildschirmpunkt -> lokales Koordinatensystem
  const local = matrix.inverse().transformPoint(
    new DOMPoint(event.clientX - rect.left - rect.width / 2,
                 event.clientY - rect.top - rect.height / 2)
  );
  console.log(`Lokal: ${local.x.toFixed(1)}, ${local.y.toFixed(1)}`);
});

Lokal: 12.3, -4.0 (abhängig vom Klick)

Matrix an WebGL übergeben

const model = new DOMMatrixReadOnly()
  .translate(0, 0, -5)
  .rotateAxisAngle(0, 1, 0, 30);

// Spaltenreihenfolge passt direkt zu uniformMatrix4fv
const data = model.toFloat32Array();
console.log(data.length);
// gl.uniformMatrix4fv(uModelLoc, false, data);

16

// Wichtig · Fallstricke

Rückgabetyp: Die Transformationsmethoden geben eine veränderbare DOMMatrix zurück, keine DOMMatrixReadOnly. Die Unveränderlichkeit gilt nur für die ursprüngliche Instanz.
Winkeleinheit: rotate(), skewX() und skewY() erwarten Grad, nicht Bogenmaß. Das ist anders als bei CanvasRenderingContext2D.rotate().
Reihenfolge: a.multiply(b) berechnet a × b. Verkettete Aufrufe wie translate().rotate() wirken wie CSS-Transformationen von rechts nach links auf Punkte.
Werte ändern sich nicht: Wenn du im nicht-strikten Modus Eigenschaften wie m.a = 5 setzt, wird das stillschweigend ignoriert. Im strikten Modus wird ein TypeError geworfen.
is2D: Sobald eine 3D-Operation angewendet wurde, etwa rotateAxisAngle oder scale3d mit z ≠ 1, bleibt is2D auf false. Das gilt auch dann, wenn die Werte später wieder 2D-kompatibel sind.
Nicht umkehrbare Matrizen: Hat die Matrix die Determinante 0, liefert inverse() eine Matrix mit lauter NaN-Werten. Es wird kein Fehler geworfen.
Worker: In Web Workern führt ein CSS-String im Konstruktor zu einem TypeError. Dort musst du Arrays verwenden.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Ältere WebKit-Versionen kannten stattdessen WebKitCSSMatrix. Die Methode scaleNonUniform() ist veraltet, nutze stattdessen scale(sx, sy).

Siehe auch

DOMMatrix DOMPoint DOMPointReadOnly DOMRect DOMMatrixReadOnly.prototype.transformPoint() DOMMatrixReadOnly.prototype.inverse() CanvasRenderingContext2D.getTransform()