CSSMatrixComponent — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSMatrixComponent extends CSSTransformComponent

Beschreibung

CSSMatrixComponent gehört zur CSS Typed Object Model API (Houdini). Die Schnittstelle steht für genau eine Transformationsfunktion matrix() oder matrix3d() innerhalb eines Werts der Eigenschaft transform. Mehrere solcher Bausteine werden in einem CSSTransformValue zusammengefasst, der dann per element.attributeStyleMap.set() gesetzt oder über computedStyleMap() gelesen werden kann.

Anders als bei Zeichenketten wie "matrix(1, 0, 0, 1, 50, 20)" arbeitet man hier mit einem echten DOMMatrix-Objekt in der Eigenschaft matrix. So lassen sich Transformationen rechnerisch verketten (multiply(), translate(), rotate() …), ohne Zeichenketten zusammenzubauen oder zu parsen. Das ist nützlich für Animationen, Drag-and-Drop oder Bibliotheken, die Transformationen häufig neu berechnen.

Wichtige Mitglieder:

new CSSMatrixComponent(matrix, options) – Konstruktor.
matrix – lesbare und schreibbare DOMMatrix mit den Matrixwerten.
is2D (geerbt) – true ergibt matrix(), false ergibt matrix3d() bei der Serialisierung.
toMatrix() (geerbt) – liefert eine neue DOMMatrix-Kopie.
toString() (geerbt) – serialisiert in CSS-Syntax.

Parameter

Name	Typ	Default	Beschreibung
$matrix Pflicht	DOMMatrixReadOnly		Die Matrix (2D oder 3D), die diese Transformationsfunktion abbildet. Intern wird sie als `DOMMatrix` gespeichert.
$options	{ is2D?: boolean }	is2D = matrix.is2D	Optionales Objekt. Mit `is2D` legst du fest, ob der Baustein als `matrix()` (`true`) oder `matrix3d()` (`false`) behandelt wird. Fehlt die Angabe, wird `matrix.is2D` übernommen.

Rückgabewert

Typ

CSSMatrixComponent

Beschreibung

Eine neue Instanz, die sich in einem CSSTransformValue verwenden lässt.

Beispiele

Instanz erzeugen und serialisieren

// 2D-Matrix: Verschiebung um 50px / 20px
const m = new DOMMatrix().translate(50, 20);
const comp = new CSSMatrixComponent(m);

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

// Dieselbe Matrix als matrix3d() erzwingen
const comp3d = new CSSMatrixComponent(m, { is2D: false });
console.log(comp3d.toString());

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

Transform eines Elements per Typed OM setzen

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

// Drehung und Skalierung in einer Matrix kombinieren
const matrix = new DOMMatrix().rotate(30).scale(1.5);
const transform = new CSSTransformValue([
  new CSSMatrixComponent(matrix)
]);

box.attributeStyleMap.set('transform', transform);
console.log(box.style.transform.startsWith('matrix('));

true

Vorhandene Matrix auslesen und weiterrechnen

const el = document.querySelector('.card');
el.style.transform = 'matrix(1, 0, 0, 1, 10, 20)';

const value = el.attributeStyleMap.get('transform'); // CSSTransformValue
const first = value[0];

if (first instanceof CSSMatrixComponent) {
  // Matrix direkt verändern: weitere 30px nach rechts
  first.matrix = first.matrix.translate(30, 0);
  el.attributeStyleMap.set('transform', value);
  console.log(first.matrix.e, first.matrix.f);
}

40 20

Feature-Erkennung mit Fallback

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

applyMatrix(document.body, new DOMMatrix().translate(0, 10));

// Wichtig · Fallstricke

Browser-Kompatibilität: Das CSS Typed OM gibt es nur in Chromium-Browsern (ab 66) und in Safari ab 16.4. Firefox unterstützt es nicht. Prüfe deshalb vorher mit 'CSSMatrixComponent' in window und sieh einen Fallback über element.style.transform vor.
Die Eigenschaft is2D ändert nur die Serialisierung. Setzt du is2D = true bei einer echten 3D-Matrix, gehen die 3D-Anteile in der Ausgabe als matrix() verloren.
toMatrix() gibt eine Kopie zurück. Änderungen daran wirken nicht auf die Komponente zurück. Weise die neue Matrix deshalb wieder comp.matrix zu und setze danach den Wert erneut per attributeStyleMap.set().
Die DOMMatrix-Methoden translate(), rotate() usw. liefern neue Matrizen. Die Varianten mit …Self() verändern die Matrix direkt an Ort und Stelle.
computedStyleMap() kann Transformationen je nach Browser anders zerlegt zurückgeben. Verlass dich also nicht darauf, dass dort immer eine CSSMatrixComponent ankommt.

Siehe auch

CSSTransformComponent CSSMathInvert AnimationEvent CSSMathClamp CSSMathMin