StylePropertyMapReadOnly.entries() — Methode · JavaScript-Referenz

Signatur

StylePropertyMapReadOnly.prototype.entries()

Beschreibung

Die Methode entries() gehört zur CSS Typed Object Model API (Houdini). Sie liefert einen Iterator, der für jede CSS-Eigenschaft der Liste ein Paar [property, values] ausgibt. property ist der Eigenschaftsname als String (z. B. "margin-top" oder eine eigene Eigenschaft wie "--akzent"). values ist ein Array von CSSStyleValue-Objekten, etwa CSSUnitValue, CSSKeywordValue oder CSSTransformValue.

Anders als es die ältere MDN-Kurzbeschreibung nahelegt, bekommst du kein Array zurück, sondern einen Iterator, so wie bei Map.prototype.entries(). Ein StylePropertyMapReadOnly ist selbst iterierbar, for (const [prop, vals] of map) verhält sich also genauso wie map.entries(). Brauchst du ein echtes Array, verwende Array.from() oder die Spread-Syntax.

Typische Quellen für ein solches Objekt sind Element.computedStyleMap() für alle berechneten Stile und Element.attributeStyleMap für die Inline-Stile (dessen Typ StylePropertyMap erbt von StylePropertyMapReadOnly). Die Methode eignet sich gut für Debugging-Werkzeuge, zum Serialisieren von Stilen und zum typisierten Auslesen vieler Eigenschaften auf einmal. Die Werte musst du dabei nicht selbst aus Strings parsen.

Rückgabewert

Typ

Iterator<[string, CSSStyleValue[]]>

Beschreibung

Ein neuer Iterator über die Paare [Eigenschaftsname, Array von CSSStyleValue]. Laut Spezifikation kommen zuerst die normalen Eigenschaften in lexikografischer Reihenfolge, danach die eigenen Eigenschaften (--*).

Beispiele

Inline-Stile eines Elements typisiert auslesen

const box = document.createElement('div');
box.style.cssText = 'width: 120px; opacity: 0.5; --akzent: tomato;';
document.body.append(box);

for (const [prop, values] of box.attributeStyleMap.entries()) {
  // values ist immer ein Array von CSSStyleValue-Objekten
  console.log(prop, values.map(v => v.toString()).join(', '));
}

opacity 0.5 width 120px --akzent tomato

Berechnete Stile filtern und in ein Objekt umwandeln

const button = document.querySelector('button');
const computed = button.computedStyleMap();

// Nur Eigenschaften, die mit "padding" beginnen
const paddings = Object.fromEntries(
  [...computed.entries()]
    .filter(([prop]) => prop.startsWith('padding-'))
    .map(([prop, [value]]) => [prop, value.toString()])
);

console.log(paddings);

{ 'padding-bottom': '1px', 'padding-left': '6px', 'padding-right': '6px', 'padding-top': '1px' }

Mit numerischen Werten rechnen, ohne Strings zu parsen

const el = document.createElement('div');
el.attributeStyleMap.set('margin-top', CSS.px(8));
el.attributeStyleMap.set('margin-bottom', CSS.px(12));

let summe = 0;
for (const [prop, [value]] of el.attributeStyleMap.entries()) {
  if (value instanceof CSSUnitValue && value.unit === 'px') {
    summe += value.value; // echte Zahl, kein "8px"-String
  }
}
console.log(`Vertikaler Außenabstand: ${summe}px`);

Vertikaler Außenabstand: 20px

// Wichtig · Fallstricke

Browser-Kompatibilität: Das CSS Typed OM gibt es in Chromium-Browsern ab Version 66 und in Safari ab 16.4. Firefox unterstützt es bisher nicht. Prüfe die Unterstützung vorher, z. B. mit if ('computedStyleMap' in Element.prototype).
Der zweite Eintrag jedes Paares ist immer ein Array, auch wenn es nur einen Wert gibt. Für den ersten Wert kannst du destrukturieren: [prop, [value]].
Du bekommst einen Iterator, kein Array. Methoden wie .filter() oder .map() brauchen vorher [...map.entries()] oder Array.from(). Ein Iterator lässt sich nur einmal durchlaufen.
computedStyleMap() liefert alle berechneten Eigenschaften, oft mehrere hundert. Es kann daher teuer sein, darüber in Schleifen oder Animationen zu iterieren. Lies einzelne Werte besser gezielt mit get() aus.
Kurzschreibweisen wie margin tauchen in der Regel nur als ausgeschriebene Einzeleigenschaften auf (margin-top usw.). Wie genau abgebildet wird, kann sich zwischen den Browsern unterscheiden.
Das von computedStyleMap() gelieferte Objekt ist eine Momentaufnahme. Änderst du danach die Stile, musst du die Methode erneut aufrufen.

Siehe auch

StylePropertyMapReadOnly.values() StylePropertyMapReadOnly.get() StylePropertyMapReadOnly.getAll() StylePropertyMapReadOnly.has() StylePropertyMapReadOnly.keys()