new CSSMatrixComponent() — Methode · JavaScript-Referenz

Signatur

new CSSMatrixComponent(matrix, options)

Beschreibung

Der Konstruktor CSSMatrixComponent() gehört zum CSS Typed Object Model (Houdini). Er verpackt ein DOMMatrixReadOnly- bzw. DOMMatrix-Objekt als Transformationskomponente, die man in einem CSSTransformValue verwenden kann. So lassen sich Transformationen typsicher über element.attributeStyleMap setzen, ohne CSS-Strings von Hand zusammenzubauen.

Ob die Komponente als matrix() (2D) oder matrix3d() (3D) ausgegeben wird, legt die Eigenschaft is2D fest. Ohne Angabe in options wird sie aus matrix.is2D übernommen. Mit { is2D: true } lässt sich die 2D-Behandlung erzwingen.

Der Konstruktor ist nützlich, wenn Transformationen zuerst mit der DOMMatrix-API berechnet werden (z. B. mit multiply(), rotate() oder translate()) und das Ergebnis danach als ein einziger Transformationsschritt auf ein Element angewendet werden soll. Das ist etwa bei Animationen, Drag-and-drop oder eigenen Layout-Berechnungen der Fall.

Parameter

Name	Typ	Default	Beschreibung
$matrix Pflicht	DOMMatrixReadOnly		Die Transformationsmatrix, die die Komponente darstellt. Es kann auch ein `DOMMatrix` sein, weil `DOMMatrix` von `DOMMatrixReadOnly` erbt.
$options	{ is2D?: boolean }	{}	Optionales Objekt. `is2D` legt fest, ob die Komponente als 2D-Transformation (`matrix()`) behandelt wird. Ohne Angabe gilt `matrix.is2D`.

Rückgabewert

Typ

CSSMatrixComponent

Beschreibung

Ein neues CSSMatrixComponent-Objekt mit den Eigenschaften matrix und is2D sowie den Methoden toMatrix() und toString().

Beispiele

2D-Matrix erzeugen und serialisieren

// Verschiebung um 50px nach rechts und 20px nach unten
const m = new DOMMatrix([1, 0, 0, 1, 50, 20]);
const comp = new CSSMatrixComponent(m);

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

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

Berechnete Transformation auf ein Element anwenden

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

// Mehrere Schritte mit DOMMatrix zusammensetzen
const matrix = new DOMMatrix()
  .translate(100, 40)
  .rotate(30)
  .scale(1.5);

const transform = new CSSTransformValue([
  new CSSMatrixComponent(matrix)
]);

box.attributeStyleMap.set('transform', transform);
console.log(box.attributeStyleMap.get('transform').toString());

matrix(1.29904, 0.75, -0.75, 1.29904, 100, 40) // Rundung je nach Browser

3D-Matrix und erzwungene 2D-Behandlung

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

const comp3d = new CSSMatrixComponent(m3d);
console.log(comp3d.is2D, comp3d.toString());

// 2D-Behandlung erzwingen
const comp2d = new CSSMatrixComponent(m3d, { is2D: true });
console.log(comp2d.is2D);

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

Funktionserkennung mit Fallback

const applyMatrix = (el, matrix) => {
  if ('CSSMatrixComponent' in window && el.attributeStyleMap) {
    el.attributeStyleMap.set(
      'transform',
      new CSSTransformValue([new CSSMatrixComponent(matrix)])
    );
  } else {
    // Fallback: String über DOMMatrix.toString()
    el.style.transform = matrix.toString();
  }
};

applyMatrix(document.body, new DOMMatrix().rotate(5));

// Wichtig · Fallstricke

Browser-Kompatibilität: Das CSS Typed OM wird in Chromium-Browsern (Chrome, Edge, Opera) ab Version 66 und in Safari ab 16.4 unterstützt. Firefox unterstützt es derzeit nicht. Deshalb vor der Nutzung prüfen, ob die API vorhanden ist ('CSSMatrixComponent' in window), und einen Fallback über element.style.transform vorsehen.
Wird für matrix kein DOMMatrixReadOnly übergeben, etwa ein normales Array, wirft der Konstruktor einen TypeError. Arrays zuerst mit new DOMMatrix([...]) umwandeln.
Mit { is2D: true } werden bei einer echten 3D-Matrix die 3D-Anteile (z. B. die Verschiebung auf der z-Achse) für Darstellung und Ausgabe ignoriert. Das kann zu unerwartetem Verhalten führen.
Die Ausgabe von toString() kann bei Nachkommastellen je nach Browser unterschiedlich gerundet sein. Werte deshalb nicht per String-Vergleich prüfen.
Ein CSSMatrixComponent allein ist kein gültiger Wert für transform. Er muss immer in einem CSSTransformValue stehen.

Siehe auch

new CSSMathInvert() new AnimationEvent() new CSSMathClamp() new CSSMathMin() new CSSMathProduct()