CSSTransformComponent.toMatrix() — Methode · JavaScript-Referenz

Signatur

CSSTransformComponent.prototype.toMatrix()

Beschreibung

toMatrix() ist auf der abstrakten Basisschnittstelle CSSTransformComponent definiert und steht damit allen konkreten Transformationsbausteinen der CSS Typed OM zur Verfügung: CSSTranslate, CSSRotate, CSSScale, CSSSkew, CSSSkewX, CSSSkewY, CSSPerspective und CSSMatrixComponent. Die Methode berechnet die 4×4-Transformationsmatrix, die der jeweiligen CSS-Transformationsfunktion (etwa translate() oder rotate()) entspricht, und liefert sie als neues DOMMatrix-Objekt zurück.

Das ist nützlich, wenn Transformationen nicht nur gesetzt, sondern mathematisch ausgewertet werden sollen: etwa um Punkte mit DOMMatrix.transformPoint() umzurechnen, mehrere Transformationen per multiply() zu kombinieren oder die tatsächliche Verschiebung (e/f) bzw. Skalierung (a/d) auszulesen.

Die Eigenschaft is2D der Komponente bestimmt, ob eine 2D- oder 3D-Matrix entsteht. Voraussetzung für die Berechnung ist, dass alle Längenangaben absolut in Pixel umrechenbar sind (px, cm, in usw.). Relative Einheiten wie %, em oder vw kann die Methode ohne Layout-Kontext nicht auflösen und wirft dann einen TypeError.

Wer die Gesamtmatrix einer kompletten transform-Liste braucht, verwendet stattdessen CSSTransformValue.prototype.toMatrix(). Diese Methode multipliziert die Matrizen aller Komponenten in der richtigen Reihenfolge.

Rückgabewert

Typ

DOMMatrix

Beschreibung

Ein neues DOMMatrix-Objekt, das der Transformationsfunktion entspricht. Ist is2D der Komponente true, ist auch matrix.is2D true.

Beispiele

Verschiebung in eine Matrix umwandeln

const translate = new CSSTranslate(CSS.px(10), CSS.px(20));
const matrix = translate.toMatrix();

console.log(matrix.is2D);      // 2D-Matrix?
console.log(matrix.e, matrix.f); // Verschiebungsanteile
console.log(matrix.toString());

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

Rotation berechnen und einen Punkt transformieren

const rotate = new CSSRotate(CSS.deg(90));
const matrix = rotate.toMatrix();

// Punkt (100, 0) um 90° drehen
const p = matrix.transformPoint(new DOMPoint(100, 0));
console.log(Math.round(p.x), Math.round(p.y));

0 100

Berechnetes transform eines Elements Schritt für Schritt auswerten

const box = document.querySelector('.box');
box.attributeStyleMap.set('transform',
  CSSStyleValue.parse('transform', 'translate(50px, 0) scale(2)'));

const transformValue = box.attributeStyleMap.get('transform'); // CSSTransformValue

for (const component of transformValue) {
  const m = component.toMatrix();
  console.log(component.constructor.name, m.toString());
}

// Gesamtmatrix aller Komponenten
console.log(transformValue.toMatrix().toString());

CSSTranslate matrix(1, 0, 0, 1, 50, 0) CSSScale matrix(2, 0, 0, 2, 0, 0) matrix(2, 0, 0, 2, 50, 0)

Fehlerfall: relative Einheiten abfangen

const translate = new CSSTranslate(CSS.percent(50), CSS.px(0));

try {
  translate.toMatrix();
} catch (err) {
  console.log(err.name); // Prozentwerte lassen sich nicht in px umrechnen
}

TypeError

// Wichtig · Fallstricke

Relative Einheiten: Enthält die Komponente Werte wie %, em, rem, vw oder calc() mit solchen Einheiten, wirft toMatrix() einen TypeError. Berechnete Werte aus element.computedStyleMap() sind meist schon absolut und daher unproblematisch.
Gleitkomma-Ungenauigkeit: Bei Rotationen entstehen Werte wie 6.123233995736766e-17 statt 0. Vor Vergleichen deshalb runden.
Kein Live-Bezug: Die zurückgegebene DOMMatrix ist eine unabhängige Kopie. Änderungen daran wirken sich weder auf die Komponente noch auf das Element aus.
2D/3D: Wird is2D einer Komponente auf true gesetzt, verwirft die Berechnung eventuell vorhandene z-Anteile.
Browser-Kompatibilität: Die CSS Typed OM wird von Chromium-Browsern (ab Chrome/Edge 66) und Safari (ab 16.4) unterstützt, von Firefox bisher nicht. Vorher per if ('CSSTranslate' in window) prüfen oder als Ausweichlösung new DOMMatrix(getComputedStyle(el).transform) verwenden.

Siehe auch

CSSTransformComponent.toString() CSSTransformValue.toMatrix() SVGTransform.setMatrix() CSSTransformValue.entries() CSSTransformValue.forEach()