CSSMatrixComponent.matrix — Eigenschaft · JavaScript-Referenz

Signatur

CSSMatrixComponent.matrix

Beschreibung

Die Eigenschaft matrix gehört zum Interface CSSMatrixComponent der CSS Typed Object Model API (Houdini). Eine CSSMatrixComponent steht für die CSS-Transformationsfunktionen matrix() und matrix3d(). Die eigentlichen Zahlenwerte liegen in einem DOMMatrix-Objekt, das du über matrix erreichst.

Du kannst die Eigenschaft lesen und schreiben. Beim Lesen bekommst du eine DOMMatrix mit den Koeffizienten a bis f (2D) bzw. m11 bis m44 (3D). Diese Werte kannst du direkt auswerten oder mit Methoden wie multiply(), translate() und inverse() weiterverarbeiten. Beim Schreiben ersetzt du die Matrix der Komponente durch eine neue DOMMatrix.

Die Eigenschaft ist nützlich, wenn du Transformationen typsicher auslesen oder ändern willst, ohne Zeichenketten wie "matrix(1, 0, 0, 1, 50, 20)" selbst zu zerlegen. Das ist zum Beispiel bei Animationen, Drag-and-drop oder beim Auswerten von computedStyleMap() praktisch.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	DOMMatrix		Nur beim Setzen: die neue Matrix, die die Komponente übernehmen soll.

Rückgabewert

Typ

DOMMatrix

Beschreibung

Die in der Komponente gespeicherte 2D- oder 3D-Transformationsmatrix.

Beispiele

Komponente erzeugen und Matrix auslesen

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

const m = component.matrix;
console.log(m.e, m.f);          // Verschiebungsanteile
console.log(m.is2D);
console.log(component.toString());

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

Matrix ersetzen und auf ein Element anwenden

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

const component = new CSSMatrixComponent(new DOMMatrix());
// Neue Matrix: drehen und skalieren
component.matrix = new DOMMatrix().rotate(45).scale(1.5);

box.attributeStyleMap.set('transform', new CSSTransformValue([component]));
console.log(box.style.transform.startsWith('matrix('));

true

Berechnete Transformation auswerten

const el = document.querySelector('.card');
el.style.transform = 'matrix(2, 0, 0, 2, 100, 0)';

const transform = el.computedStyleMap().get('transform');
for (const part of transform) {
  if (part instanceof CSSMatrixComponent) {
    const { a, d, e } = part.matrix;
    console.log(`Skalierung: ${a}×${d}, Versatz X: ${e}px`);
  }
}

Skalierung: 2×2, Versatz X: 100px

// Wichtig · Fallstricke

Browser-Unterstützung: Die CSS Typed OM API gibt es in Chromium-Browsern (Chrome, Edge, Opera) und seit Version 16.4 in Safari. Firefox unterstützt sie nicht. Prüfe deshalb vorher mit 'CSSMatrixComponent' in window.
Das Flag is2D der Komponente ist unabhängig von matrix.is2D. Es legt fest, ob toString() die Funktion matrix() oder matrix3d() ausgibt.
Wenn du die Matrix nur liest und direkt veränderst (z. B. mit multiplySelf()), wird das Element nicht automatisch aktualisiert. Du musst den CSSTransformValue danach erneut mit attributeStyleMap.set() zuweisen.
Die Methoden rotate(), scale() usw. einer DOMMatrix geben eine neue Matrix zurück. Nur die Varianten mit ...Self() verändern die bestehende Matrix.
Ob computedStyleMap() eine CSSMatrixComponent oder einzelne Komponenten wie CSSTranslate liefert, hängt vom Browser ab. Prüfe den Typ deshalb immer mit instanceof.

Siehe auch

TaskAttributionTiming.containerId CSSMathInvert.value CSSTransformComponent.is2D CustomEvent.detail SVGTransform.matrix