DOMMatrixReadOnly.toJSON() — Methode · JavaScript-Referenz

Signatur

DOMMatrixReadOnly.prototype.toJSON()

Beschreibung

Die Methode toJSON() wandelt eine DOMMatrixReadOnly oder eine DOMMatrix in ein einfaches JavaScript-Objekt um. Trotz des Namens gibt sie keinen JSON-String zurück, sondern ein Objekt, das JSON.stringify() anschließend in Text umwandeln kann. Dieses Objekt enthält alle Eigenschaften der Matrix: die 2D-Kurzformen a bis f, die 16 Werte m11 bis m44 sowie die booleschen Werte is2D und isIdentity.

Normalerweise ruft man toJSON() gar nicht selbst auf: JSON.stringify() nutzt die Methode automatisch, sobald ein DOMMatrix-Objekt im Wert vorkommt, auch verschachtelt in anderen Objekten oder Arrays. Ohne toJSON() käme nur {} heraus, weil die Matrix-Werte Getter auf dem Prototyp sind und keine eigenen Eigenschaften.

Typische Einsätze sind das Speichern von Transformationen, etwa Zoom- oder Pan-Zustände eines Canvas-Editors in localStorage, das Senden an einen Server und das Debugging. Wiederherstellen lässt sich die Matrix mit DOMMatrix.fromMatrix() oder DOMMatrixReadOnly.fromMatrix(), denn das zurückgegebene Objekt passt zum Wörterbuch DOMMatrixInit.

Rückgabewert

Typ

Object

Beschreibung

Ein einfaches Objekt mit den Zahlen-Eigenschaften a, b, c, d, e, f, m11–m44 und den booleschen Eigenschaften is2D und isIdentity.

Beispiele

Matrix direkt in ein Objekt umwandeln

const matrix = new DOMMatrix().translate(10, 20);
const obj = matrix.toJSON();

console.log(obj.e, obj.f);        // Verschiebung in 2D-Kurzform
console.log(obj.m41, obj.m42);    // dieselben Werte in 4×4-Form
console.log(obj.is2D, obj.isIdentity);

10 20 10 20 true false

Automatischer Aufruf durch JSON.stringify()

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

// JSON.stringify ruft toJSON() selbst auf
console.log(JSON.stringify(matrix));

{"a":1,"b":0,"c":0,"d":1,"e":10,"f":20,"m11":1,"m12":0,"m13":0,"m14":0,"m21":0,"m22":1,"m23":0,"m24":0,"m31":0,"m32":0,"m33":1,"m34":0,"m41":10,"m42":20,"m43":0,"m44":1,"is2D":true,"isIdentity":false}

Zoom-/Pan-Zustand eines Canvas speichern und wiederherstellen

const saveView = (matrix) => {
  localStorage.setItem('viewTransform', JSON.stringify({ transform: matrix }));
};

const loadView = () => {
  const raw = localStorage.getItem('viewTransform');
  if (!raw) return new DOMMatrix();
  const { transform } = JSON.parse(raw);
  // is2D / isIdentity werden von fromMatrix berücksichtigt bzw. ignoriert
  return DOMMatrix.fromMatrix(transform);
};

const view = new DOMMatrix().scale(2).translate(50, 30);
saveView(view);

const restored = loadView();
console.log(restored.toString());

const ctx = document.querySelector('canvas').getContext('2d');
ctx.setTransform(restored);

matrix(2, 0, 0, 2, 100, 60)

// Wichtig · Fallstricke

Kein String: toJSON() gibt ein Objekt zurück. Für Text braucht es zusätzlich JSON.stringify().
Keine Rückumwandlung durch JSON.parse(): Heraus kommt nur ein einfaches Objekt. Eine echte Matrix erhältst du erst mit DOMMatrix.fromMatrix(obj).
Nicht-endliche Werte: NaN und Infinity werden in JSON zu null, -0 wird zu 0. Beim Wiederherstellen wird null zu 0, dabei gehen also still Daten verloren.
Rundungsfehler: Nach rotate() stehen oft Werte wie 6.123233995736766e-17 statt 0 in der Matrix. Wenn nötig, vor dem Speichern runden.
Prüfung bei fromMatrix(): Ist is2D: true gesetzt, obwohl 3D-Werte ungleich 0 bzw. 1 vorkommen, oder passen a und m11 nicht zusammen, wird ein TypeError ausgelöst.
Kompatibilität: Die Methode ist in allen modernen Browsern und in Web Workern verfügbar. Node.js hat kein eingebautes DOMMatrix, dort braucht es ein Polyfill (z. B. aus jsdom- oder Canvas-Paketen).

Siehe auch

DOMMatrixReadOnly DOMMatrix DOMMatrix.fromMatrix() DOMMatrixReadOnly.toString() DOMMatrixReadOnly.toFloat64Array() JSON.stringify() NotRestoredReasonDetails.toJSON()