CSSUnparsedValue.values() — Methode · JavaScript-Referenz

Signatur

CSSUnparsedValue.prototype.values()

Beschreibung

Die Methode values() gehört zum Interface CSSUnparsedValue aus dem CSS Typed Object Model (Houdini). Ein CSSUnparsedValue steht für einen CSS-Wert, den der Browser nicht weiter auswertet. Typisch sind das Werte eigener Eigenschaften (--foo) oder Werte, die var()-Verweise enthalten. Intern ist der Wert eine Liste aus Zeichenketten-Stücken und CSSVariableReferenceValue-Objekten.

values() gibt einen Iterator zurück, der diese Bestandteile der Reihe nach liefert. Damit kannst du einen Wert Stück für Stück untersuchen, etwa um herauszufinden, auf welche Variablen ein Wert verweist, oder um ihn umzubauen und neu zu setzen. Die Methode verhält sich wie Array.prototype.values(). Weil CSSUnparsedValue selbst iterierbar ist, liefern for...of direkt auf dem Objekt und [...value.values()] dasselbe Ergebnis.

Du brauchst die Methode vor allem, wenn du mit element.attributeStyleMap, element.computedStyleMap() oder in CSS Paint Worklets arbeitest und Werte eigener Eigenschaften auswerten willst, ohne selbst Zeichenketten zu zerlegen.

Rückgabewert

Typ

Iterator<string | CSSVariableReferenceValue>

Beschreibung

Ein neuer Array-Iterator, der jeden Bestandteil des CSSUnparsedValue in der gespeicherten Reihenfolge liefert: entweder eine string oder ein CSSVariableReferenceValue.

Beispiele

Bestandteile eines selbst gebauten Werts durchlaufen

// Entspricht dem CSS-Wert: "1px solid var(--akzent)"
const wert = new CSSUnparsedValue([
  '1px solid ',
  new CSSVariableReferenceValue('--akzent')
]);

for (const teil of wert.values()) {
  if (typeof teil === 'string') {
    console.log('Text:', JSON.stringify(teil));
  } else {
    console.log('Variable:', teil.variable);
  }
}

Text: "1px solid " Variable: --akzent

Verwendete CSS-Variablen einer eigenen Eigenschaft ermitteln

const box = document.querySelector('.box');
box.style.setProperty('--abstand', 'calc(var(--basis) * 2 + var(--extra))');

const wert = box.attributeStyleMap.get('--abstand');

if (wert instanceof CSSUnparsedValue) {
  const variablen = [...wert.values()]
    .filter((teil) => teil instanceof CSSVariableReferenceValue)
    .map((teil) => teil.variable);
  console.log(variablen);
}

["--basis", "--extra"]

Iterator von Hand weiterschalten

const wert = new CSSUnparsedValue(['rot ', new CSSVariableReferenceValue('--x')]);
const it = wert.values();

console.log(it.next()); // erstes Stück
console.log(it.next().value.variable);
console.log(it.next().done);

{ value: "rot ", done: false } --x true

// Wichtig · Fallstricke

Browser-Kompatibilität: Das CSS Typed OM gibt es in Chromium-Browsern (Chrome, Edge, Opera) seit Version 66. Safari unterstützt es ab Version 16.4, Firefox bislang nicht. Prüfe vorher mit if ('CSSUnparsedValue' in window), ob die API da ist.
Der Iterator ist eine Momentaufnahme des Ablaufs, keine Kopie: Änderst du den CSSUnparsedValue während der Schleife (z. B. über Index-Zuweisung wert[0] = '...'), wirkt sich das auf die weitere Iteration aus.
Wie die Zeichenketten-Stücke aufgeteilt sind, hängt davon ab, wie der Browser den Wert zerlegt. Leerzeichen und Klammern landen in den Text-Stücken. Vergleiche Text-Stücke also nicht zu streng.
Ein Iterator lässt sich nur einmal durchlaufen. Für eine zweite Runde rufst du values() erneut auf oder wandelst das Ergebnis mit Array.from() in ein Array um.
Verschachtelte Rückfallwerte wie var(--a, var(--b)) stecken in CSSVariableReferenceValue.fallback, das wieder ein CSSUnparsedValue ist. Um sie zu erfassen, musst du rekursiv durchlaufen.

Siehe auch

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