DOMMatrixReadOnly.toString() — Methode · JavaScript-Referenz

Signatur

DOMMatrixReadOnly.prototype.toString()

Beschreibung

Die Methode toString() ist der Stringifier von DOMMatrixReadOnly und damit auch von DOMMatrix. Sie wandelt die Matrix in eine Zeichenkette um, die sich direkt als Wert der CSS-Eigenschaft transform verwenden lässt. Weil sie der Stringifier ist, wird sie automatisch aufgerufen, sobald die Matrix in einem Zeichenketten-Kontext steht, etwa in Template-Literalen, bei String(matrix) oder bei einer Zuweisung an element.style.transform.

Das Format hängt von der Eigenschaft is2D ab:

is2D === true: matrix(a, b, c, d, e, f). Das sind die sechs Werte m11, m12, m21, m22, m41, m42.
is2D === false: matrix3d(m11, m12, m13, m14, m21, …, m44). Das sind alle 16 Werte in spaltenweiser Reihenfolge (column-major), so wie CSS sie erwartet.

Die Zahlen werden wie bei JavaScript-Zahlen üblich serialisiert und mit ", " getrennt. Enthält die Matrix einen nicht endlichen Wert (NaN, Infinity oder -Infinity), wirft die Methode einen DOMException vom Typ InvalidStateError, weil ein solcher Wert keine gültige CSS-Transformation ergibt.

Typische Einsatzfälle: eine per JavaScript berechnete Transformation auf ein Element anwenden, Matrizen beim Debuggen lesbar ausgeben oder eine Transformation als Zeichenkette speichern und später mit new DOMMatrix(string) wiederherstellen.

Rückgabewert

Typ

string

Beschreibung

Eine CSS-Transformationsfunktion als Zeichenkette: matrix(…) mit 6 Werten bei 2D-Matrizen oder matrix3d(…) mit 16 Werten bei 3D-Matrizen. Wirft InvalidStateError, wenn ein Matrixwert nicht endlich ist.

Beispiele

Einheitsmatrix und 2D-Transformation serialisieren

const identity = new DOMMatrixReadOnly();
console.log(identity.toString());

// Erst verschieben, dann gleichmäßig skalieren – bleibt eine 2D-Matrix
const m = new DOMMatrix().translate(10, 20).scale(2);
console.log(m.is2D, String(m));

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

3D-Transformation ergibt matrix3d()

const m3d = new DOMMatrix().translate(10, 20, 30);
console.log(m3d.is2D);
console.log(`${m3d}`);

false matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 10, 20, 30, 1)

Berechnete Transformation auf ein Element anwenden

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

// Aktuelle Transformation aus dem berechneten Stil lesen
const current = new DOMMatrix(getComputedStyle(box).transform);

// 50px nach rechts verschieben und um 1.5 vergrößern
const next = current.translate(50, 0).scale(1.5);

// Beim Zuweisen wird toString() automatisch aufgerufen
box.style.transform = next;
console.log(box.style.transform);

matrix(1.5, 0, 0, 1.5, 50, 0) // wenn .box vorher keine Transformation hatte

Nicht endliche Werte abfangen

const broken = new DOMMatrix([1, 0, 0, 1, Infinity, 0]);

try {
  broken.toString();
} catch (err) {
  console.log(err.name);
}

InvalidStateError

// Wichtig · Fallstricke

Ausnahme bei nicht endlichen Werten: Durch Division durch 0 oder das Invertieren einer singulären Matrix (invertSelf() setzt dann alle Werte auf NaN) entstehen leicht ungültige Werte. toString() wirft dann InvalidStateError, auch bei implizitem Aufruf wie el.style.transform = m. Vorher mit Number.isFinite() prüfen oder den Aufruf in try/catch einschließen.
2D oder 3D: Das Ausgabeformat hängt von is2D ab, nicht von den Zahlenwerten. Eine Matrix, die aus einem matrix3d()-String oder mit einem Array aus 16 Werten erzeugt wurde, bleibt auch dann 3D, wenn sie mathematisch einer 2D-Matrix entspricht.
Gleitkomma-Genauigkeit: Bei Rotationen entstehen Werte wie 6.123233995736766e-17 statt 0. Für lesbare Ausgaben sollte man die Werte selbst runden, z. B. mit m.toFloat64Array() und toFixed().
Round-Trip: Die Zeichenkette lässt sich mit new DOMMatrix(str) wieder einlesen. Dieser Konstruktor-Weg über CSS-Syntax funktioniert nur im Fenster-Kontext, nicht in Workern.
Kompatibilität: In allen modernen Browsern verfügbar. Das ältere WebKitCSSMatrix ist in vielen Browsern ein Alias von DOMMatrix.

Siehe auch

DOMMatrixReadOnly DOMMatrix DOMMatrixReadOnly.toJSON() DOMMatrixReadOnly.toFloat64Array() DOMMatrixReadOnly.is2D DOMMatrixReadOnly.translate()