CSSTransformValue.toMatrix() — Methode · JavaScript-Referenz

Signatur

CSSTransformValue.prototype.toMatrix()

Beschreibung

toMatrix() gehört zum CSS Typed Object Model (Houdini). Ein CSSTransformValue ist eine Liste einzelner Transformationen wie CSSTranslate, CSSRotate, CSSScale, CSSSkew, CSSPerspective oder CSSMatrixComponent. Die Methode wandelt jede davon in eine Matrix um und multipliziert sie von links nach rechts. Heraus kommt eine einzige DOMMatrix, die genau der Transformation entspricht, die der Browser auf das Element anwendet.

Das hilft, wenn du mit einer Transformation rechnen musst, statt sie nur zu setzen. Typische Fälle: einen Punkt mit DOMMatrix.transformPoint() in das transformierte Koordinatensystem umrechnen, die Transformation mit inverse() umkehren (z. B. um Mauskoordinaten zurückzurechnen) oder mehrere Transformationen zu einem matrix()-String zusammenfassen.

Die zurückgegebene Matrix ist ein neues, unabhängiges Objekt. Wenn du sie änderst, ändert sich der ursprüngliche CSSTransformValue nicht. Sind alle Bestandteile zweidimensional (is2D === true), ist auch die Matrix 2D (matrix.is2D === true). Sonst entsteht eine 4×4-Matrix.

Rückgabewert

Typ

DOMMatrix

Beschreibung

Eine neue DOMMatrix: das Produkt der Matrizen aller Transformationsbestandteile, in der Reihenfolge der Liste.

Beispiele

Transformation aufbauen und in eine Matrix umwandeln

const transform = new CSSTransformValue([
  new CSSTranslate(CSS.px(100), CSS.px(50)),
  new CSSRotate(CSS.deg(90))
]);

const matrix = transform.toMatrix();
const round = (n) => Math.round(n * 1000) / 1000;

console.log(matrix.is2D);
console.log([matrix.a, matrix.b, matrix.c, matrix.d, matrix.e, matrix.f].map(round));

true [0, 1, -1, 0, 100, 50]

Punkt eines Elements in transformierte Koordinaten umrechnen

const box = document.querySelector('.box');
box.attributeStyleMap.set('transform', new CSSTransformValue([
  new CSSTranslate(CSS.px(20), CSS.px(10)),
  new CSSScale(2, 2)
]));

const transform = box.attributeStyleMap.get('transform');
const matrix = transform.toMatrix();

// Wohin wandert die Ecke (50|25) durch die Transformation?
const p = matrix.transformPoint(new DOMPoint(50, 25));
console.log(p.x, p.y);

// Umgekehrt: Bildschirmpunkt ins ursprüngliche Koordinatensystem zurückrechnen
const back = matrix.inverse().transformPoint(p);
console.log(back.x, back.y);

120 60 50 25

Mehrere Transformationen zu einem matrix()-String zusammenfassen

const transform = new CSSTransformValue([
  new CSSScale(2, 3),
  new CSSTranslate(CSS.px(5), CSS.px(5))
]);

// Reihenfolge zählt: erst skalieren, dann (im skalierten System) verschieben
console.log(transform.toMatrix().toString());

matrix(2, 0, 0, 3, 10, 15)

Relative Einheiten führen zu einem TypeError

const transform = new CSSTransformValue([
  new CSSTranslate(CSS.percent(50), CSS.px(0))
]);

try {
  transform.toMatrix();
} catch (err) {
  console.log(err.name); // Prozentwerte lassen sich ohne Layout nicht auflösen
}

TypeError

// Wichtig · Fallstricke

TypeError bei relativen Längen: Enthält ein Bestandteil Längen, die sich nicht ohne Layout in px umrechnen lassen (z. B. %, em, vw oder ein calc() mit solchen Einheiten), wirft toMatrix() einen TypeError. Die Methode kennt die Elementgröße nicht. Nutze absolute Einheiten (px, deg, rad, turn) oder fange den Fehler ab.
Reihenfolge: Die Matrizen werden in der Reihenfolge der Liste multipliziert, genau wie bei der CSS-Eigenschaft transform. translate + rotate ergibt ein anderes Ergebnis als rotate + translate.
Kein Transform-Origin: transform-origin wird nicht eingerechnet. Die Matrix bezieht sich auf den Nullpunkt. Für die tatsächliche Position auf dem Bildschirm musst du den Ursprung selbst mit einer Verschiebung davor und danach berücksichtigen.
Rundung: Winkelfunktionen liefern Gleitkommawerte wie 6.123e-17 statt 0. Runde vor Vergleichen oder Ausgaben.
Browser-Unterstützung: CSS Typed OM gibt es in Chromium-Browsern (ab Version 66) und in Safari (ab 16.4), aber nicht in Firefox. Prüfe vorher, ob die API vorhanden ist, z. B. mit if ('CSSTransformValue' in window). Als Ersatz kannst du new DOMMatrix(getComputedStyle(el).transform) verwenden.
Für transform: none liefert computedStyleMap().get('transform') ein CSSKeywordValue, keinen CSSTransformValue. Dort gibt es kein toMatrix().

Siehe auch

CSSTransformValue.entries() CSSTransformValue.forEach() CSSTransformValue.values() CSSTransformValue.keys() CSSTransformComponent.toMatrix()