new CSSTransformValue() — Methode · JavaScript-Referenz

Signatur

new CSSTransformValue(transforms)

Beschreibung

Der Konstruktor CSSTransformValue() gehört zum CSS Typed Object Model (Houdini). Er fasst eine Folge einzelner Transformationen wie CSSTranslate, CSSRotate, CSSScale, CSSSkew, CSSPerspective oder CSSMatrixComponent zu einem Wert zusammen, der einer CSS-transform-Eigenschaft entspricht, zum Beispiel translate(10px, 20px) rotate(45deg).

Man verwendet ihn, wenn man Transformationen typisiert aufbauen will, statt Zeichenketten zusammenzusetzen und vom Browser parsen zu lassen. Das Ergebnis weist man über element.attributeStyleMap.set('transform', wert) zu. Das ist sicherer gegen Tippfehler und bei häufigen Änderungen, etwa in Animationsschleifen, oft schneller, weil das Parsen von Strings entfällt.

Das erzeugte Objekt ist iterierbar und über Indizes ansprechbar wie ein Array (wert[0], wert.length). Außerdem gibt es die Eigenschaft is2D und die Methode toMatrix(), die die ganze Liste zu einer DOMMatrix zusammenrechnet.

Parameter

Name	Typ	Default	Beschreibung
$transforms Pflicht	Iterable<CSSTransformComponent>		Eine nicht leere Liste (z. B. ein Array) von `CSSTransformComponent`-Objekten. Die Reihenfolge ist wichtig, weil sie der Reihenfolge der Funktionen in der `transform`-Eigenschaft entspricht.

Rückgabewert

Typ

CSSTransformValue

Beschreibung

Ein neues CSSTransformValue-Objekt mit den übergebenen Transformationen in der angegebenen Reihenfolge.

Beispiele

Transformation typisiert aufbauen und zuweisen

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

const transform = new CSSTransformValue([
  new CSSTranslate(CSS.px(10), CSS.px(20)),
  new CSSRotate(CSS.deg(45)),
  new CSSScale(1.5, 1.5)
]);

box.attributeStyleMap.set('transform', transform);

console.log(transform.length);
console.log(transform.toString());

3 translate(10px, 20px) rotate(45deg) scale(1.5, 1.5)

is2D prüfen und in eine DOMMatrix umrechnen

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

console.log(transform.is2D);

const matrix = transform.toMatrix();
// Punkt (1, 0) mit der gesamten Transformation abbilden
const p = matrix.transformPoint(new DOMPoint(1, 0));
console.log(Math.round(p.x), Math.round(p.y));

true 100 1

Einzelne Transformation in einer Animationsschleife ändern

const el = document.querySelector('.spinner');
const rotation = new CSSRotate(CSS.deg(0));
const transform = new CSSTransformValue([
  new CSSTranslate(CSS.percent(-50), CSS.percent(-50)),
  rotation
]);

const tick = (time) => {
  // Nur den Winkel ändern, kein String-Parsing nötig
  rotation.angle.value = (time / 10) % 360;
  el.attributeStyleMap.set('transform', transform);
  requestAnimationFrame(tick);
};

if ('CSSTransformValue' in window) {
  requestAnimationFrame(tick);
} else {
  console.warn('CSS Typed OM wird nicht unterstützt');
}

Über die Komponenten iterieren

const transform = new CSSTransformValue([
  new CSSTranslate(CSS.px(5), CSS.px(5)),
  new CSSSkew(CSS.deg(10), CSS.deg(0)),
  new CSSScale(2, 2)
]);

for (const component of transform) {
  console.log(component.constructor.name, component.is2D);
}

CSSTranslate true CSSSkew true CSSScale true

// Wichtig · Fallstricke

Leere Liste: new CSSTransformValue([]) löst einen TypeError aus. Es muss mindestens eine Komponente übergeben werden.
Nur passende Typen: Jedes Element muss ein CSSTransformComponent sein. Strings wie 'rotate(45deg)' werden nicht angenommen. Zum Parsen von Strings dient CSSStyleValue.parse('transform', '…').
toMatrix() und relative Einheiten: Enthält die Liste Werte in %, em oder calc() mit relativen Anteilen, kann keine absolute Matrix berechnet werden. In diesem Fall löst toMatrix() einen TypeError aus.
is2D ist nur true, wenn alle Komponenten zweidimensional sind. Schon ein einziges CSSTranslate mit z-Wert macht das Ergebnis 3D.
Browser-Unterstützung: CSS Typed OM gibt es in Chromium-Browsern ab Version 66 und in Safari ab 16.4, in Firefox dagegen nicht. Prüfe vorher mit 'CSSTransformValue' in window, ob die API vorhanden ist, und weiche sonst auf element.style.transform = '…' aus.

Siehe auch

new CSSKeywordValue() new CSSTranslate() new CSSPositionValue() new CSSUnitValue() new CSSUnparsedValue()