CSSTransformValue — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSTransformValue extends CSSStyleValue

Beschreibung

CSSTransformValue gehört zur CSS Typed Object Model API (Houdini) und steht für einen transform-list-Wert, also den Inhalt der CSS-Eigenschaft transform. Statt eine Zeichenkette wie "translate(10px, 20px) rotate(45deg)" zusammenzubauen oder mit regulären Ausdrücken zu zerlegen, arbeitest du mit echten Objekten: Jede Transformationsfunktion ist ein eigenes CSSTransformComponent, z. B. CSSTranslate, CSSRotate, CSSScale, CSSSkew, CSSSkewX, CSSSkewY, CSSPerspective oder CSSMatrixComponent.

Die Schnittstelle verhält sich wie ein Array: Sie hat die Eigenschaft length, erlaubt indizierten Lese- und Schreibzugriff (value[0]) und bietet die Iterator-Methoden entries(), keys(), values() und forEach(), sodass auch for...of funktioniert. Zusätzlich gibt es:

is2D (nur lesend): true, wenn alle Komponenten 2D-Transformationen sind.
toMatrix(): rechnet die gesamte Liste in eine einzelne DOMMatrix um.
toString() (von CSSStyleValue geerbt): serialisiert den Wert zurück in gültige CSS-Syntax.

Du bekommst eine Instanz, wenn du transform über element.attributeStyleMap.get() oder element.computedStyleMap().get() ausliest. Eigene Instanzen erzeugst du mit new CSSTransformValue(transforms) und setzt sie per attributeStyleMap.set('transform', value). Das ist vor allem bei Animationen oder interaktiven Transformationen nützlich, weil du einzelne Werte gezielt ändern kannst, ohne jedes Mal Zeichenketten neu zu parsen.

Parameter

Name	Typ	Default	Beschreibung
$transforms Pflicht	Array<CSSTransformComponent>		Konstruktor-Argument: nicht leeres Array von Transformationskomponenten (z. B. `CSSTranslate`, `CSSRotate`, `CSSScale`). Die Reihenfolge entspricht der Reihenfolge der Funktionen in CSS.

Rückgabewert

Typ

CSSTransformValue

Beschreibung

Der Konstruktor new CSSTransformValue(transforms) liefert eine neue Instanz, die du per attributeStyleMap.set() einem Element zuweisen kannst.

Beispiele

Transformation erzeugen und einem Element 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.is2D);
console.log(transform.toString());

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

Bestehenden transform-Wert auslesen und durchlaufen

const card = document.querySelector('.card');
card.style.transform = 'translateX(50px) rotate(30deg)';

const value = card.attributeStyleMap.get('transform');
console.log(value instanceof CSSTransformValue);

for (const component of value) {
  console.log(component.constructor.name, component.toString());
}

true CSSTranslate translate(50px, 0px) CSSRotate rotate(30deg)

In eine DOMMatrix umrechnen

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

const matrix = transform.toMatrix();
console.log(matrix.a, matrix.d, matrix.e, matrix.f);

// Punkt transformieren, z. B. für Kollisionsprüfung
const point = new DOMPoint(5, 5).matrixTransform(matrix);
console.log(point.x, point.y);

2 2 10 20 20 30

Einzelne Komponente in einer Animation ändern

const spinner = document.querySelector('.spinner');
const rotate = new CSSRotate(CSS.deg(0));
const transform = new CSSTransformValue([
  new CSSTranslate(CSS.px(0), CSS.px(0)),
  rotate
]);

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

requestAnimationFrame(tick);

// Wichtig · Fallstricke

Browserunterstützung: Chromium-Browser (Chrome, Edge, Opera) ab Version 66, Safari ab 16.4. Firefox unterstützt das CSS Typed OM bisher nicht. Prüfe die Verfügbarkeit mit if ('CSSTransformValue' in window) und greife sonst auf element.style.transform mit Zeichenketten zurück.
Der Konstruktor wirft einen TypeError, wenn du ein leeres Array übergibst. Den Wert none kann CSSTransformValue nicht darstellen; er wird beim Auslesen als CSSKeywordValue geliefert. Prüfe also vor dem Iterieren mit instanceof.
toMatrix() wirft einen TypeError, wenn Komponenten relative Längen wie em, % oder calc() enthalten, die sich ohne Layout-Kontext nicht in px umrechnen lassen.
Änderungen an der Instanz (oder ihren Komponenten) wirken sich nicht automatisch auf das Element aus. Du musst den Wert danach erneut mit attributeStyleMap.set() zuweisen.
is2D ist nur lesbar und wird aus den Komponenten abgeleitet. Eine einzige 3D-Komponente, z. B. CSSTranslate mit z-Wert oder CSSPerspective, macht den ganzen Wert zu einem 3D-Wert.
Die Reihenfolge ist wichtig: Transformationen werden von links nach rechts verkettet. translate gefolgt von rotate ergibt ein anderes Ergebnis als die umgekehrte Reihenfolge.

Siehe auch

CSSKeywordValue CSSTranslate CSSImageValue CSSMathValue CSSNumericValue