CSSUnparsedValue.forEach() — Methode · JavaScript-Referenz

Signatur

CSSUnparsedValue.prototype.forEach(callbackFn, thisArg)

Beschreibung

CSSUnparsedValue gehört zum CSS Typed Object Model. Dieses Objekt steht für einen CSS-Wert, den der Browser nicht weiter auswertet. Das betrifft vor allem nicht registrierte Custom Properties wie --foo: calc(var(--gap) * 2). Der Wert besteht aus einer geordneten Liste von Segmenten. Jedes Segment ist entweder eine string (Rohtext) oder ein CSSVariableReferenceValue (ein var()-Verweis).

forEach() funktioniert wie Array.prototype.forEach(): Die Methode ruft die übergebene Funktion für jedes Segment in der gespeicherten Reihenfolge auf. Die Funktion erhält dabei das Segment, seinen Index und das CSSUnparsedValue-Objekt selbst.

Typische Einsätze sind das Untersuchen oder Protokollieren von Custom-Property-Werten, das Sammeln aller verwendeten var()-Abhängigkeiten und das Umbauen von Werten in eigenen Werkzeugen, etwa beim Theming oder in Design-Token-Werkzeugen. Wenn du ein Ergebnis brauchst, etwa ein gefiltertes Array, sind Array.from(value) oder die Spread-Syntax meist die bessere Wahl, weil CSSUnparsedValue iterierbar ist, aber keine Methoden wie map oder filter hat.

Parameter

Name	Typ	Default	Beschreibung
$callbackFn Pflicht	(currentValue: string \| CSSVariableReferenceValue, index: number, obj: CSSUnparsedValue) => void		Wird für jedes Segment aufgerufen. Sie erhält `currentValue` (das aktuelle Segment), `index` (seine Position) und `obj` (den durchlaufenen `CSSUnparsedValue`). Ihr Rückgabewert wird ignoriert.
$thisArg	any	undefined	Wert, der beim Aufruf von `callbackFn` als `this` verwendet wird. Bei Pfeilfunktionen hat er keine Wirkung.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. forEach() dient nur zum Durchlaufen und lässt sich nicht verketten.

Beispiele

Segmente eines selbst erzeugten Werts ausgeben

const value = new CSSUnparsedValue([
  'calc(',
  new CSSVariableReferenceValue('--gap'),
  ' * 2)'
]);

value.forEach((segment, index) => {
  if (typeof segment === 'string') {
    console.log(index, `Text: "${segment}"`);
  } else {
    console.log(index, `Variable: ${segment.variable}`);
  }
});

0 Text: "calc(" 1 Variable: --gap 2 Text: " * 2)"

var()-Abhängigkeiten einer Custom Property sammeln

const button = document.querySelector('button');
button.style.setProperty('--button-bg', 'var(--brand) linear-gradient(var(--accent), white)');

const raw = button.attributeStyleMap.get('--button-bg');
const deps = new Set();

if (raw instanceof CSSUnparsedValue) {
  raw.forEach((segment) => {
    if (segment instanceof CSSVariableReferenceValue) {
      deps.add(segment.variable);
    }
  });
}

console.log([...deps]);

["--brand", "--accent"]

thisArg mit einer normalen Funktion nutzen

const value = new CSSUnparsedValue(['1px solid ', new CSSVariableReferenceValue('--border-color')]);

const collector = { parts: [] };

value.forEach(function (segment) {
  // this zeigt auf collector
  this.parts.push(String(segment));
}, collector);

console.log(collector.parts.join(''));

1px solid var(--border-color)

// Wichtig · Fallstricke

Browser-Unterstützung: CSS Typed OM gibt es in Chromium-Browsern (Chrome, Edge, Opera) ab Version 66 und in Safari ab 16.4. Firefox unterstützt es derzeit nicht. Prüfe deshalb vorher, ob es verfügbar ist, z. B. mit if ('CSSUnparsedValue' in window).
Segmente können Zeichenketten oder CSSVariableReferenceValue sein. Prüfe den Typ mit typeof oder instanceof, bevor du auf Eigenschaften wie .variable zugreifst.
Der Rückfallwert (fallback) eines var()-Verweises ist selbst ein CSSUnparsedValue. forEach() durchläuft nur die oberste Ebene. Verschachtelte Verweise musst du selbst rekursiv verarbeiten.
Wie bei Array.prototype.forEach() kannst du nicht mit break abbrechen. Verwende dafür for...of.
Wie der Browser die Segmente aufteilt, z. B. ob leere Zeichenketten zwischen Verweisen entstehen, kann je nach Engine leicht abweichen. Verlasse dich daher nicht auf feste Indizes.
Registrierte Custom Properties (über CSS.registerProperty() oder @property) liefern typisierte Werte wie CSSUnitValue und keinen CSSUnparsedValue.

Siehe auch

Array.prototype.forEach() CSSUnparsedValue.keys() CSSUnparsedValue.entries() CSSUnparsedValue.values() CSSTransformValue.forEach()