Signatur
Beschreibung
Die Methode entries() gehört zur Schnittstelle CSSUnparsedValue aus dem CSS Typed Object Model (Houdini). Ein CSSUnparsedValue steht für einen CSS-Wert, den der Browser nicht weiter auswertet. Das betrifft vor allem nicht registrierte Custom Properties (--foo) und Werte mit var()-Verweisen. Intern besteht er aus einer Liste von Segmenten. Jedes Segment ist entweder ein string oder ein CSSVariableReferenceValue.
entries() liefert einen Iterator über diese Segmente. Jeder Schritt gibt ein Paar [index, segment] zurück. Das ist nützlich, wenn du beim Durchlaufen die Position eines Segments brauchst. Ein Beispiel: Du willst herausfinden, an welcher Stelle ein var()-Verweis steht, und diesen Verweis gezielt ersetzen.
Die Methode verhält sich wie Array.prototype.entries(). Der Iterator funktioniert mit for...of, dem Spread-Operator und Array.from(). Ergänzend gibt es keys(), values() und forEach(). Außerdem ist ein CSSUnparsedValue selbst iterierbar und hat eine Eigenschaft length.
Rückgabewert
number) und dem Segment (string oder CSSVariableReferenceValue).Beispiele
Segmente mit Index durchlaufen
const value = new CSSUnparsedValue([
'1px solid ',
new CSSVariableReferenceValue('--border-color')
]);
for (const [index, segment] of value.entries()) {
const text = typeof segment === 'string'
? `Text: "${segment}"`
: `Variable: ${segment.variable}`;
console.log(index, text);
}Position eines var()-Verweises finden und ersetzen
const value = new CSSUnparsedValue([
'0 0 4px ',
new CSSVariableReferenceValue('--accent')
]);
// Index des ersten Variablen-Verweises ermitteln
const hit = [...value.entries()]
.find(([, seg]) => seg instanceof CSSVariableReferenceValue);
if (hit) {
const [index] = hit;
value[index] = new CSSVariableReferenceValue('--accent-dark');
}
console.log(value.toString());Custom Property eines Elements analysieren
const box = document.querySelector('.box');
box.style.setProperty('--shadow', '0 2px 8px var(--shadow-color)');
const parsed = box.attributeStyleMap.get('--shadow');
if (parsed instanceof CSSUnparsedValue) {
const entries = Array.from(parsed.entries(), ([i, seg]) =>
`${i}: ${typeof seg === 'string' ? seg.trim() : `var(${seg.variable})`}`
);
console.log(entries);
}// Wichtig · Fallstricke
- Browser-Unterstützung: Das CSS Typed OM gibt es in Chromium-Browsern (Chrome und Edge ab Version 66) und in Safari ab 16.4. Firefox unterstützt
CSSUnparsedValuederzeit nicht. Prüfe die Unterstützung vorher, zum Beispiel mitif ('CSSUnparsedValue' in window). - Segmente können unterschiedliche Typen haben:
stringoderCSSVariableReferenceValue. Prüfe den Typ vor jedem Zugriff, etwa mittypeofoderinstanceof. - Wie der Browser die Segmente aufteilt und wie er Leerzeichen behandelt, kann sich zwischen den Engines leicht unterscheiden. Verlasse dich nicht auf exakte Zeichenketten und verwende bei Bedarf
trim(). - Der Iterator ist „live“: Änderst du die Liste während des Durchlaufs, wirkt sich das auf die weiteren Schritte aus. Wenn du beim Durchlaufen ändern willst, erzeuge vorher eine Kopie mit
[...value.entries()]. - Für Custom Properties, die mit
CSS.registerProperty()registriert sind, liefernattributeStyleMapundcomputedStyleMap()in der Regel typisierte Werte, zum BeispielCSSUnitValue, und keinenCSSUnparsedValue.