DOMMatrixReadOnly.is2D — Eigenschaft · JavaScript-Referenz

Signatur

DOMMatrixReadOnly.is2D

Beschreibung

is2D gibt an, ob eine DOMMatrixReadOnly bzw. DOMMatrix eine reine 2D-Matrix ist. Eine 2D-Matrix hat die Form einer 3×2-Matrix mit den Werten a bis f. Die übrigen Werte einer 4×4-Matrix (m13, m14, m23, m24, m31–m34, m43) haben dann ihre Standardwerte (0), m33 und m44 sind 1.

Wichtig: is2D ist ein Zustands-Flag und wird nicht jedes Mal neu aus den aktuellen Werten berechnet. Es wird beim Erzeugen gesetzt: true für eine leere Initialisierung, ein Array mit 6 Werten oder einen 2D-CSS-Transform-String, false für ein Array mit 16 Werten oder matrix3d()/3D-Funktionen. Danach wird es auf false gesetzt, sobald eine 3D-Operation angewendet wird (z. B. translate mit tz ≠ 0, rotate um die X- oder Y-Achse, scale mit scaleZ ≠ 1, Multiplikation mit einer 3D-Matrix oder bei DOMMatrix das Setzen einer 3D-Komponente auf einen Nicht-Standardwert). Ist das Flag einmal false, wird es nicht wieder true, selbst wenn die 3D-Anteile später wieder rechnerisch neutral sind.

In der Praxis entscheidet is2D zum Beispiel darüber, ob toString() einen matrix(...)- oder einen matrix3d(...)-String liefert. Außerdem lässt sich damit prüfen, ob eine Matrix gefahrlos an 2D-APIs wie CanvasRenderingContext2D.setTransform() übergeben werden kann, ohne dass 3D-Informationen verloren gehen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Matrix eine 2D-Matrix ist, sonst false. Die Eigenschaft ist schreibgeschützt, auch bei DOMMatrix.

Beispiele

Flag je nach Art der Erzeugung

const leer = new DOMMatrixReadOnly();
const sechs = new DOMMatrixReadOnly([1, 0, 0, 1, 50, 20]);
const sechzehn = new DOMMatrixReadOnly([
  1, 0, 0, 0,
  0, 1, 0, 0,
  0, 0, 1, 0,
  0, 0, 0, 1
]);

console.log(leer.is2D);          // leere Initialisierung
console.log(sechs.is2D);         // 6 Werte
console.log(sechzehn.is2D);      // 16 Werte -> 3D
console.log(sechzehn.isIdentity); // trotzdem Einheitsmatrix

true true false true

3D-Operation setzt is2D dauerhaft auf false

const m = new DOMMatrix();

m.translateSelf(10, 20);
console.log(m.is2D, m.toString());

m.translateSelf(0, 0, 5);   // Verschiebung in Z-Richtung
console.log(m.is2D);

m.translateSelf(0, 0, -5);  // rechnerisch wieder neutral ...
console.log(m.is2D);        // ... Flag bleibt aber false
console.log(m.toString());

true matrix(1, 0, 0, 1, 10, 20) false false matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 10, 20, 0, 1)

Berechnetes CSS-Transform prüfen

const box = document.querySelector('.box');
box.style.transform = 'rotateY(30deg) translateX(40px)';

const { transform } = getComputedStyle(box);
const matrix = new DOMMatrixReadOnly(transform);

if (matrix.is2D) {
  console.log('Reine 2D-Transformation');
} else {
  console.log('3D-Transformation erkannt:', transform.startsWith('matrix3d'));
}

3D-Transformation erkannt: true

Matrix nur als 2D an Canvas übergeben

const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');

const applyTransform = (matrix) => {
  if (!matrix.is2D) {
    console.warn('3D-Anteile würden ignoriert – Transformation übersprungen');
    return false;
  }
  ctx.setTransform(matrix);
  return true;
};

console.log(applyTransform(new DOMMatrix().rotate(45)));
console.log(applyTransform(new DOMMatrix().rotate(45, 0, 0)));

true 3D-Anteile würden ignoriert – Transformation übersprungen false

// Wichtig · Fallstricke

Flag statt Berechnung: is2D sagt nicht aus, ob die Matrix rechnerisch 2D ist. Eine Matrix aus 16 Werten, die eigentlich eine 2D-Matrix darstellen, liefert trotzdem false. Wenn du es rechnerisch prüfen willst, vergleiche die 3D-Komponenten selbst (m13 === 0, m33 === 1 usw.).
Nicht umkehrbar: Nach einer 3D-Operation bleibt das Flag false. Brauchst du wieder eine 2D-Matrix, erzeuge sie neu, z. B. mit DOMMatrix.fromMatrix({ a, b, c, d, e, f }).
Schreibgeschützt: Zuweisungen wie m.is2D = true werden ignoriert (im Strict Mode gibt es einen TypeError). Bei fromMatrix() kann is2D im Init-Objekt angegeben werden. Widerspricht der Wert den Komponenten (z. B. is2D: true mit m33: 2), wird ein TypeError geworfen.
Kompatibilität: In allen aktuellen Browsern und Web Workern verfügbar. Der Konstruktor mit CSS-String funktioniert jedoch nur im Fenster-Kontext, nicht in Workern. Node.js stellt DOMMatrix nicht nativ bereit.

Siehe auch

DOMMatrixReadOnly.isIdentity DOMPointReadOnly.w DOMPointReadOnly.x DOMPointReadOnly.y DOMPointReadOnly.z MediaTrackSettings.cursor NotRestoredReasons.reasons