DOMMatrix.fromMatrix() — Methode · JavaScript-Referenz

Signatur

DOMMatrix.fromMatrix(other)

Beschreibung

DOMMatrix.fromMatrix() ist eine statische Fabrikmethode. Sie nimmt ein Objekt im Format DOMMatrixInit entgegen und gibt eine neue, unabhängige DOMMatrix zurück. Das kann eine vorhandene DOMMatrix oder DOMMatrixReadOnly sein, aber auch ein einfaches Objekt wie { a: 2, d: 2, e: 50 }.

Typische Einsatzfälle:

Kopieren einer Matrix, bevor man sie mit *Self()-Methoden (z. B. translateSelf(), scaleSelf()) verändert. Die Ausgangsmatrix bleibt dabei unverändert.
Umwandeln einer schreibgeschützten DOMMatrixReadOnly in eine veränderbare DOMMatrix.
Übernehmen von Matrix-Werten aus serialisierten Daten (JSON, postMessage, Speicher). Dort liegen die Werte nur als einfaches Objekt vor.

Fehlende Werte werden mit denen der Einheitsmatrix aufgefüllt: m11, m22, m33 und m44 bekommen 1, alle anderen 0. Die 2D-Aliase (a, b, c, d, e, f) und die zugehörigen 4×4-Einträge (m11, m12, m21, m22, m41, m42) bezeichnen dieselben Werte. Wird is2D nicht angegeben, bestimmt der Browser die Eigenschaft selbst: Sie ist true, wenn keine 3D-Werte vom Standard abweichen.

Parameter

Name	Typ	Default	Beschreibung
$other	DOMMatrix \| DOMMatrixReadOnly \| DOMMatrixInit	{} (Einheitsmatrix)	Quellmatrix oder Objekt mit beliebigen der Eigenschaften `a`–`f`, `m11`–`m44` und `is2D`. Ohne Argument entsteht die Einheitsmatrix.

Rückgabewert

Typ

DOMMatrix

Beschreibung

Eine neue DOMMatrix mit den übernommenen bzw. ergänzten Werten. Sie ist vom Quellobjekt unabhängig.

Beispiele

Matrix kopieren, ohne das Original zu verändern

const base = new DOMMatrix().translate(10, 20).rotate(45);
const copy = DOMMatrix.fromMatrix(base);

// Nur die Kopie wird skaliert
copy.scaleSelf(2);

console.log(base.a, copy.a);

0.7071067811865476 1.4142135623730951

Matrix aus einfachem Objekt (z. B. aus JSON) erzeugen

const saved = JSON.parse('{"a":2,"d":2,"e":50,"f":10}');
const m = DOMMatrix.fromMatrix(saved);

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

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

Berechnete CSS-Transformation erweitern

const box = document.querySelector('.box');
const current = new DOMMatrixReadOnly(getComputedStyle(box).transform);

// Schreibgeschützte Matrix in eine veränderbare umwandeln
const next = DOMMatrix.fromMatrix(current).translateSelf(30, 0).rotateSelf(15);

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

Widersprüchliche Werte führen zu TypeError

try {
  // a und m11 bezeichnen denselben Eintrag, hier aber mit verschiedenen Werten
  DOMMatrix.fromMatrix({ a: 1, m11: 2 });
} catch (err) {
  console.log(err.name);
}

try {
  // is2D: true, obwohl ein 3D-Wert gesetzt ist
  DOMMatrix.fromMatrix({ is2D: true, m33: 5 });
} catch (err) {
  console.log(err.name);
}

TypeError TypeError

// Wichtig · Fallstricke

TypeError bei Widersprüchen: Gibt man sowohl einen 2D-Alias als auch den zugehörigen m-Wert an (z. B. a und m11) und unterscheiden sich die Werte, wird ein Fehler geworfen. Dasselbe gilt für is2D: true, wenn gleichzeitig 3D-Werte vom Standard abweichen, z. B. m33 ≠ 1 oder m13 ≠ 0.
Keine Zeichenketten: fromMatrix() nimmt keine CSS-Transformations-Zeichenkette an. Dafür ist der Konstruktor da: new DOMMatrix('rotate(45deg)').
Kopie, keine Referenz: Das Ergebnis ist immer ein neues Objekt. Änderungen daran wirken sich nicht auf die Quelle aus.
Schreibgeschützte Variante: DOMMatrixReadOnly.fromMatrix() funktioniert genauso, liefert aber eine nicht veränderbare Matrix.
Kompatibilität: Wird von allen aktuellen Browsern und in Web Workern unterstützt. Node.js hat kein DOMMatrix; dort braucht man ein Polyfill, z. B. aus canvas- oder jsdom-Paketen.
Mit fromFloat32Array() bzw. fromFloat64Array() erzeugt man Matrizen aus Arrays mit 6 oder 16 Zahlen, etwa für WebGL-Daten.

Siehe auch

DOMMatrix DOMMatrixReadOnly DOMMatrix.fromFloat32Array() DOMMatrix.fromFloat64Array() DOMMatrixReadOnly.fromMatrix() DOMMatrix.prototype.multiplySelf()