DOMMatrixReadOnly.fromMatrix() — Methode · JavaScript-Referenz

Signatur

DOMMatrixReadOnly.fromMatrix(other)

Beschreibung

DOMMatrixReadOnly.fromMatrix() ist eine statische Fabrikmethode. Sie nimmt ein Objekt im Format DOMMatrixInit entgegen und liefert daraus ein neues DOMMatrixReadOnly. Das Objekt kann eine echte DOMMatrix bzw. ein DOMMatrixReadOnly sein oder ein einfaches Objekt mit den Eigenschaften a bis f (2D-Kurzform) und/oder m11 bis m44 (volle 4×4-Matrix) sowie optional is2D.

Typische Einsatzfälle sind:

eine unveränderliche Kopie einer veränderlichen DOMMatrix anlegen, z. B. als Zwischenstand oder Ausgangszustand einer Animation,
Matrixwerte, die als JSON gespeichert oder per postMessage übertragen wurden, wieder in ein Matrixobjekt umwandeln,
eine Transformation aus einzelnen Werten aufbauen, ohne einen CSS-Transform-String zusammenzusetzen.

Fehlende Werte werden mit denen der Einheitsmatrix aufgefüllt. Lässt man is2D weg, ermittelt der Browser den Wert selbst: Die Matrix gilt als 2D, solange alle 3D-Anteile (m13, m14, m23, m24, m31, m32, m34, m43 = 0 sowie m33, m44 = 1) ihre Standardwerte haben. Widersprüchliche Angaben führen zu einem TypeError.

Parameter

Name	Typ	Default	Beschreibung
$other	DOMMatrixInit \| DOMMatrix \| DOMMatrixReadOnly	{} (Einheitsmatrix)	Quelle der Matrixwerte. Mögliche Eigenschaften: `a`–`f`, `m11`–`m44` (jeweils `number`) und `is2D` (`boolean`). `a`/`m11`, `b`/`m12`, `c`/`m21`, `d`/`m22`, `e`/`m41` und `f`/`m42` sind Aliase und müssen übereinstimmen, wenn beide angegeben werden.

Rückgabewert

Typ

DOMMatrixReadOnly

Beschreibung

Ein neues, unveränderliches Matrixobjekt mit den übergebenen bzw. ergänzten Werten. Das Objekt ist unabhängig von der Quelle; spätere Änderungen an der Quelle wirken sich nicht darauf aus.

Beispiele

2D-Matrix aus einem einfachen Objekt erstellen

// Verschiebung um 50px nach rechts und 20px nach unten
const matrix = DOMMatrixReadOnly.fromMatrix({ a: 1, b: 0, c: 0, d: 1, e: 50, f: 20 });

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

// Direkt als CSS-Transformation verwenden
document.querySelector('.box').style.transform = matrix.toString();

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

Unveränderliche Kopie einer DOMMatrix als Ausgangszustand

const live = new DOMMatrix().translate(10, 20);

// Zwischenstand sichern, bevor weitergerechnet wird
const snapshot = DOMMatrixReadOnly.fromMatrix(live);

live.translateSelf(5, 0).scaleSelf(2);

console.log(snapshot.e, snapshot.a); // Kopie bleibt unverändert
console.log(live.e, live.a);

10 1 15 2

Gespeicherte Matrixwerte aus JSON wiederherstellen (inkl. 3D)

const json = '{"m11":1,"m22":1,"m33":1,"m43":100}';
const restored = DOMMatrixReadOnly.fromMatrix(JSON.parse(json));

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

// Punkt transformieren
const p = restored.transformPoint({ x: 0, y: 0, z: 0 });
console.log(p.z);

false matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 100, 1) 100

Widersprüchliche Werte abfangen

const tryCreate = (init) => {
  try {
    return DOMMatrixReadOnly.fromMatrix(init);
  } catch (err) {
    console.log(`${err.name}: ungültige Matrixdaten`);
    return null;
  }
};

tryCreate({ a: 2, m11: 3 });          // a und m11 widersprechen sich
tryCreate({ is2D: true, m33: 2 });    // 3D-Wert trotz is2D: true
console.log(tryCreate({ a: 2, m11: 2 }).a); // identische Aliase sind erlaubt

TypeError: ungültige Matrixdaten TypeError: ungültige Matrixdaten 2

// Wichtig · Fallstricke

TypeError bei Widersprüchen: Werden Alias-Paare wie a und m11 mit unterschiedlichen Werten angegeben oder ist is2D: true gesetzt, obwohl 3D-Anteile von ihren Standardwerten abweichen, wirft die Methode einen TypeError. Daten aus externen Quellen daher mit try…catch absichern.
Keine CSS-Strings: fromMatrix() akzeptiert keine Zeichenketten wie "translate(10px, 20px)". Dafür den Konstruktor new DOMMatrixReadOnly("…") verwenden, der nur im Hauptthread CSS-Syntax parst, nicht in Workern.
Unveränderlich: Das Ergebnis besitzt keine …Self()-Methoden. Methoden wie translate() oder multiply() geben jeweils eine neue DOMMatrix zurück. Wer ein veränderliches Objekt braucht, nimmt DOMMatrix.fromMatrix().
Fehlende Werte werden still mit der Einheitsmatrix ergänzt. Tippfehler in Eigenschaftsnamen (z. B. M11) werden daher nicht gemeldet, sondern einfach ignoriert.
Die Methode wird von allen aktuellen Browsern unterstützt. Ältere WebKit-Versionen kannten nur WebKitCSSMatrix, das keine fromMatrix()-Methode hat.

Siehe auch

DOMMatrixReadOnly.rotate() DOMMatrixReadOnly.toString() DOMMatrixReadOnly.flipX() DOMMatrixReadOnly.translate() DOMMatrixReadOnly.flipY() CSSTransformComponent.toMatrix()