CSSStyleValue.toString() — Methode · JavaScript-Referenz

Signatur

CSSStyleValue.prototype.toString()

Beschreibung

Die Methode toString() gehört zur CSS Typed Object Model API (Houdini). Sie ist als Stringifier festgelegt: Sie wandelt ein typisiertes Wertobjekt wie CSSUnitValue, CSSMathSum, CSSKeywordValue oder CSSTransformValue wieder in normalen CSS-Text um.

Weil es ein Stringifier ist, wird die Methode auch implizit aufgerufen, etwa bei Template-Literalen (`${value}`), bei String(value) oder bei der Verkettung mit +. Das hilft, wenn man Werte zum Debuggen ausgibt, sie in klassische APIs wie element.style.setProperty() einsetzt oder sie als Text speichert.

Das Ergebnis ist eine normalisierte Serialisierung und nicht unbedingt der Text, den man ursprünglich geschrieben hat. Zahlen werden normalisiert, Leerzeichen vereinheitlicht und mathematische Ausdrücke meist in calc() gesetzt.

Rückgabewert

Typ

string

Beschreibung

Der Wert als serialisierter CSS-Text, z. B. "42px", "auto" oder "calc(1px + 2em)".

Beispiele

Einheitenwert in CSS-Text umwandeln

const breite = CSS.px(120);
console.log(breite.toString());

// Implizit über Template-Literal
console.log(`Breite: ${breite}`);

120px Breite: 120px

Berechneten Ausdruck serialisieren

// 100% - 2rem als typisierter Ausdruck
const ausdruck = CSS.percent(100).sub(CSS.rem(2));
console.log(ausdruck.constructor.name);
console.log(ausdruck.toString());

CSSMathSum calc(100% - 2rem)

Wert aus computedStyleMap lesen und weitergeben

const box = document.querySelector('.box');
const padding = box.computedStyleMap().get('padding-top');

// Typisierten Wert als Text an eine klassische API übergeben
const text = padding.toString();
box.style.setProperty('--gespeichertes-padding', text);
console.log(text);

16px

Geparsten Wert normalisiert ausgeben

const wert = CSSStyleValue.parse('transform', 'translateX(10px)   rotate(45deg)');
console.log(String(wert));

translateX(10px) rotate(45deg)

// Wichtig · Fallstricke

Normalisierung: Die Ausgabe muss nicht mit dem ursprünglichen Text übereinstimmen. Deshalb sollte man keine Zeichenketten vergleichen, um Werte gleichzusetzen. Besser ist es, die typisierten Eigenschaften zu vergleichen, z. B. value und unit.
Browser-Unterstützung: Das CSS Typed OM gibt es seit Langem in Chromium-Browsern (ab Version 66). Safari unterstützt es ab 16.4, Firefox erst seit Kurzem (ab Version 145). Für ältere Browser prüft man die Unterstützung mit if ('CSSStyleValue' in window) oder if (window.CSS?.px).
Nicht registrierte Custom Properties werden oft als CSSUnparsedValue geliefert. Deren toString() gibt den Token-Text weitgehend so zurück, wie er geschrieben wurde.
computedStyleMap() liefert berechnete Werte. toString() gibt dann z. B. Pixel statt em zurück.

Siehe auch

CSSNumericValue.equals() CSSStyleValue.parse() CSSStyleValue.parseAll() Selection.toString() TrustedHTML.toString()