CSSTransformComponent — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSTransformComponent

Beschreibung

CSSTransformComponent ist das gemeinsame Basis-Interface aller Objekte der CSS Typed Object Model API, die genau eine Transformationsfunktion der CSS-Eigenschaft transform darstellen. Ein vollständiger transform-Wert wird als CSSTransformValue abgebildet. Das ist eine Liste, deren Einträge jeweils ein CSSTransformComponent sind.

Das Interface ist abstrakt. Du erzeugst also nie direkt ein CSSTransformComponent, sondern immer eine der konkreten Unterklassen:

CSSTranslate: translate(), translate3d()
CSSRotate: rotate(), rotate3d()
CSSScale: scale(), scale3d()
CSSSkew, CSSSkewX, CSSSkewY: skew(), skewX(), skewY()
CSSPerspective: perspective()
CSSMatrixComponent: matrix(), matrix3d()

Alle Unterklassen erben von der Basis drei Dinge: die les- und schreibbare Eigenschaft is2D, die Methode toMatrix(), die die Funktion in eine DOMMatrix umrechnet, und toString(), die die Funktion als CSS-Text ausgibt. Die Klasse ist nützlich, wenn du Transformationen typsicher auslesen, zerlegen und verändern willst, ohne Strings wie "rotate(30deg) scale(2)" selbst parsen zu müssen. Das ist praktisch für Animationen, Editoren oder Drag-and-drop.

Rückgabewert

Typ

CSSTransformComponent

Beschreibung

Keine eigene Instanz möglich. Instanzen entstehen nur über Unterklassen wie CSSRotate oder CSSTranslate oder beim Auslesen von transform über attributeStyleMap bzw. computedStyleMap(). Geerbte Mitglieder: is2D (boolean), toMatrix() (gibt eine DOMMatrix zurück) und toString() (gibt einen string zurück).

Beispiele

Unterklassen erzeugen und als CSSTransformComponent erkennen

const rotate = new CSSRotate(CSS.deg(45));
const scale = new CSSScale(1.5, 1.5);

console.log(rotate instanceof CSSTransformComponent); // true
console.log(scale instanceof CSSTransformComponent);  // true
console.log(rotate.toString());
console.log(scale.toString());

// Die abstrakte Basis selbst lässt sich nicht instanziieren
try {
  new CSSTransformComponent();
} catch (err) {
  console.log(err.name);
}

true true rotate(45deg) scale(1.5, 1.5) TypeError

transform eines Elements in Einzelfunktionen zerlegen

const box = document.querySelector('.box');
box.style.transform = 'translate(10px, 20px) rotate(30deg) scale(2)';

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

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

CSSTranslate translate(10px, 20px) true CSSRotate rotate(30deg) true CSSScale scale(2, 2) true

is2D umschalten und in DOMMatrix umrechnen

const move = new CSSTranslate(CSS.px(10), CSS.px(20), CSS.px(30));
console.log(move.is2D, move.toString());

// Als 2D behandeln: Die z-Komponente wird bei Ausgabe und Matrix ignoriert
move.is2D = true;
console.log(move.toString());

const matrix = move.toMatrix(); // DOMMatrix
console.log(matrix.is2D, matrix.e, matrix.f);

false translate3d(10px, 20px, 30px) translate(10px, 20px) true 10 20

Transformation typsicher zusammensetzen und setzen

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

const setTilt = (angleDeg, zoom) => {
  const value = new CSSTransformValue([
    new CSSPerspective(CSS.px(600)),
    new CSSRotate(0, 1, 0, CSS.deg(angleDeg)),
    new CSSScale(zoom, zoom)
  ]);
  card.attributeStyleMap.set('transform', value);
};

setTilt(20, 1.1);
console.log(card.style.transform);

perspective(600px) rotate3d(0, 1, 0, 20deg) scale(1.1, 1.1)

// Wichtig · Fallstricke

Abstrakt: new CSSTransformComponent() wirft einen TypeError. Verwende immer eine konkrete Unterklasse.
toMatrix() und relative Einheiten: Enthält die Funktion Werte, die sich nicht in px umrechnen lassen (z. B. %, em, vw oder calc() mit solchen Anteilen), wirft toMatrix() einen TypeError. Lies in diesem Fall besser über computedStyleMap() aus oder rechne die Einheiten vorher selbst um.
is2D ist nur ein Flag: Setzt du es auf true, wird die 3D-Information (z. B. die z-Verschiebung) nicht gelöscht, sondern nur bei Ausgabe und Matrix ignoriert. Bei CSSPerspective hat das Setzen keine Wirkung, der Wert bleibt false.
Serialisierung: Die genaue Ausgabe von toString() kann sich je nach Browser leicht unterscheiden (z. B. scale(2) gegenüber scale(2, 2)). Vergleiche Transformationen deshalb nicht als Strings.
Browser-Kompatibilität: Die CSS Typed OM gibt es in Chromium-Browsern ab Version 66 und in Safari ab 16.4. Firefox unterstützt sie bisher nicht. Prüfe die Verfügbarkeit per if ('CSSTransformComponent' in window) und nutze sonst element.style.transform als String.
Als Teil der Houdini-APIs gibt es das Interface auch in Worklets, z. B. in Paint Worklets.

Siehe auch

CSSMatrixComponent CSSTransformValue RTCTransformEvent CSSTransition SVGTransformList