DOMMatrix.setMatrixValue() — Methode · JavaScript-Referenz

Signatur

DOMMatrix.prototype.setMatrixValue(transformList)

Beschreibung

setMatrixValue() wandelt eine Zeichenkette mit CSS-Transformationsfunktionen wie "translate(10px, 20px) rotate(45deg)" in eine Matrix um und überschreibt damit alle Werte der vorhandenen DOMMatrix. Die Methode verändert die Matrix direkt und gibt sie selbst zurück. Deshalb lassen sich weitere …Self()-Methoden wie translateSelf() oder scaleSelf() direkt anhängen.

Nützlich ist das, wenn Sie Transformationen schon als CSS-Text haben, etwa aus getComputedStyle(el).transform, aus einer Konfiguration oder aus Nutzereingaben, und damit rechnen möchten: Punkte umrechnen mit transformPoint(), die Matrix umkehren mit invertSelf() oder mehrere Matrizen verknüpfen. Anders als mit dem Konstruktor new DOMMatrix(string) müssen Sie dafür kein neues Objekt anlegen. Sie können also eine Matrix, die Sie ohnehin behalten, immer wieder neu belegen, zum Beispiel in einer Animationsschleife.

Die Transformationen werden von links nach rechts verknüpft, genau wie bei der CSS-Eigenschaft transform. Das Ergebnis bestimmt auch is2D: Stehen nur 2D-Funktionen in der Zeichenkette, ist is2D danach true. Kommen 3D-Funktionen wie translateZ(), rotateX() oder matrix3d() vor, ist es false. Mit "none" oder einer leeren Zeichenkette wird die Matrix auf die Einheitsmatrix zurückgesetzt.

Parameter

Name	Typ	Default	Beschreibung
$transformList Pflicht	string		Liste von CSS-Transformationsfunktionen, z. B. `"scale(2) rotate(30deg)"`, `"matrix(1, 0, 0, 1, 5, 5)"` oder `"none"`. Erlaubt sind nur absolute Längen wie `px`, keine relativen Einheiten wie `%` oder `em`.

Rückgabewert

Typ

DOMMatrix

Beschreibung

Dieselbe, jetzt veränderte DOMMatrix-Instanz (this). Damit lassen sich Aufrufe verketten.

Beispiele

Matrix aus einer CSS-Transform-Zeichenkette setzen

const m = new DOMMatrix();
m.setMatrixValue('translate(10px, 20px) rotate(90deg)');

console.log(m.e, m.f);           // Verschiebung
console.log(m.a.toFixed(3), m.b.toFixed(3)); // Rotationsanteil
console.log(m.is2D);

10 20 0.000 1.000 true

Berechnete Transformation eines Elements auslesen und einen Punkt umrechnen

const box = document.querySelector('.box');
box.style.transform = 'translate(100px, 50px) scale(2)';

const m = new DOMMatrix();
const css = getComputedStyle(box).transform; // z. B. "matrix(2, 0, 0, 2, 100, 50)"
m.setMatrixValue(css);

const p = m.transformPoint(new DOMPoint(10, 10));
console.log(p.x, p.y);

120 70

Eine Matrix wiederverwenden und Aufrufe verketten

const m = new DOMMatrix();
const el = document.querySelector('.spinner');
let angle = 0;

const tick = () => {
  angle = (angle + 2) % 360;
  // Dieselbe Instanz neu belegen, dann weiter transformieren
  m.setMatrixValue(`rotate(${angle}deg)`).scaleSelf(1.5);
  el.style.transform = m.toString();
  requestAnimationFrame(tick);
};
requestAnimationFrame(tick);

Ungültige Eingaben abfangen und 3D erkennen

const m = new DOMMatrix();

const trySet = (value) => {
  try {
    m.setMatrixValue(value);
    console.log(`${value} → is2D: ${m.is2D}`);
  } catch (err) {
    console.log(`${value} → ${err.name}`);
  }
};

trySet('translateZ(50px)');
trySet('translate(50%, 0)');
trySet('drehen(10deg)');
trySet('none');

translateZ(50px) → is2D: false translate(50%, 0) → SyntaxError drehen(10deg) → SyntaxError none → is2D: true

// Wichtig · Fallstricke

Nur im Window-Kontext: In Web Workern gibt es setMatrixValue() nicht, weil dort kein CSS-Parser zur Verfügung steht. Dasselbe gilt für den String-Konstruktor. In Workern setzen Sie die Werte über ein Zahlen-Array (new DOMMatrix([a, b, c, d, e, f])) oder mit DOMMatrix.fromMatrix().
SyntaxError: Die Methode wirft einen DOMException vom Typ SyntaxError, wenn die Zeichenkette nicht gültig ist. Das passiert auch bei relativen Einheiten (%, em, vw …), weil sich diese ohne Element-Kontext nicht auflösen lassen. Bei Nutzereingaben daher immer try…catch verwenden.
Verändert die Matrix direkt: Die bisherigen Werte gehen verloren. Wenn Sie das Original noch brauchen, legen Sie vorher eine Kopie an, z. B. mit DOMMatrix.fromMatrix(m).
Ist die Matrix eine DOMMatrixReadOnly, gibt es die Methode nicht.
Die Reihenfolge der Transformationen ist wichtig: "rotate(45deg) translate(100px)" ergibt eine andere Matrix als "translate(100px) rotate(45deg)".
Werden Sie mit toString() zurück in Text umgewandelt, können Gleitkommawerte leicht ungenau sein (z. B. 6.123e-17 statt 0).

Siehe auch

DOMMatrix DOMMatrix.translateSelf() DOMMatrix.multiplySelf() DOMMatrix.invertSelf() DOMMatrixReadOnly.transformPoint() DOMMatrixReadOnly.is2D