CSSTransformComponent.toString() — Methode · JavaScript-Referenz

Signatur

CSSTransformComponent.prototype.toString()

Beschreibung

toString() ist der Stringifier des Interfaces CSSTransformComponent. Die Methode wandelt eine einzelne Transformationskomponente aus dem CSS Typed Object Model in die CSS-Schreibweise um, also etwa rotate(45deg), scale(2, 2) oder matrix(1, 0, 0, 1, 10, 20). Aufgerufen wird sie auf einer konkreten Unterklasse wie CSSTranslate, CSSRotate, CSSScale, CSSSkew, CSSSkewX, CSSSkewY, CSSPerspective oder CSSMatrixComponent.

Welche CSS-Funktion dabei herauskommt, hängt von der Eigenschaft is2D ab. Eine 2D-Komponente wird zum Beispiel als translate() ausgegeben, eine 3D-Komponente als translate3d(). Numerische Werte werden mit ihrer Einheit serialisiert, etwa 10px oder 45deg.

Nützlich ist die Methode bei der Fehlersuche und beim Protokollieren. Außerdem braucht man sie, wenn eine Transformation, die im Typed OM zusammengesetzt wurde, als String weitergegeben werden soll, etwa an element.style.transform, an eine Bibliothek oder an die Web Animations API. Da es sich um einen Stringifier handelt, wird sie auch automatisch in Template-Literalen und bei der Verkettung mit Strings aufgerufen.

Rückgabewert

Typ

string

Beschreibung

Die CSS-Transform-Funktion als String, z. B. "rotate(45deg)" oder "translate3d(10px, 20px, 5px)".

Beispiele

Einzelne Komponenten in CSS-Strings umwandeln

const verschieben = new CSSTranslate(CSS.px(10), CSS.px(20));
const drehen = new CSSRotate(CSS.deg(45));
const skalieren = new CSSScale(2, 2);

console.log(verschieben.toString());
console.log(drehen.toString());
console.log(skalieren.toString());

translate(10px, 20px) rotate(45deg) scale(2, 2)

2D- und 3D-Ausgabe hängt von is2D ab

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

const r3d = new CSSRotate(0, 0, 1, CSS.deg(90));
console.log(r3d.toString());

// Eine 2D-Komponente zwingend als 3D ausgeben
const t = new CSSTranslate(CSS.px(10), CSS.px(20));
t.is2D = false;
console.log(t.toString());

false translate3d(10px, 20px, 5px) rotate3d(0, 0, 1, 90deg) translate3d(10px, 20px, 0px)

Transform eines Elements zerlegen und protokollieren

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

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

for (const komponente of transform) {
  console.log(`${komponente.constructor.name}: ${komponente}`);
}

CSSTranslate: translate(50px, 0px) CSSRotate: rotate(30deg) CSSScale: scale(1.5, 1.5)

Komponente anpassen und als String zurückschreiben

const el = document.querySelector('.karte');
const drehung = new CSSRotate(CSS.deg(0));

el.addEventListener('pointermove', (e) => {
  drehung.angle = CSS.deg(e.offsetX / 10);
  // Stringifier wird automatisch aufgerufen
  el.style.transform = `${drehung}`;
});

// Wichtig · Fallstricke

Browser-Unterstützung: Das CSS Typed OM gibt es in Chromium-Browsern ab Version 66 und in Safari ab 16.4. Firefox unterstützt es nicht. Vorher mit if ('CSSTransformComponent' in window) prüfen.
Das Ergebnis ist eine normalisierte Schreibweise und nicht unbedingt der ursprüngliche Text. Aus translateX(50px) wird zum Beispiel translate(50px, 0px), aus scale(1.5) wird scale(1.5, 1.5). Kurzformen lassen sich also nicht zurückgewinnen.
Wer is2D manuell auf true setzt, bekommt eine 2D-Funktion. Eventuell vorhandene z-Werte werden in der Ausgabe dann ignoriert.
CSSTransformComponent selbst ist abstrakt und kann nicht direkt mit new erzeugt werden. Man arbeitet immer mit den Unterklassen.
Mit computedStyleMap() wird transform in der Regel als aufgelöste Matrix geliefert (CSSMatrixComponent). Die ursprünglichen Einzelfunktionen bekommt man eher über attributeStyleMap.
Für eine komplette Transformationsliste gibt es CSSTransformValue.toString(). Diese Methode verbindet alle Komponenten mit Leerzeichen.

Siehe auch

CSSTransformComponent.toMatrix() CSSTransformValue.toMatrix() CSSTransformValue.entries() HTMLAnchorElement.toString() CSSTransformValue.forEach()