StylePropertyMapReadOnly.values() — Methode · JavaScript-Referenz

Signatur

StylePropertyMapReadOnly.prototype.values()

Beschreibung

Die Methode values() gehört zur CSS Typed Object Model API (Houdini). Sie gibt einen Iterator zurück, der die Werte aller Einträge einer StylePropertyMapReadOnly in ihrer Reihenfolge durchläuft. Jeder Eintrag ist ein Array von CSSStyleValue-Objekten, weil manche CSS-Eigenschaften mehrere Werte haben können (z. B. transition-property oder background-image mit mehreren Ebenen).

Eine StylePropertyMapReadOnly bekommst du meist über element.computedStyleMap(), das die berechneten Stile eines Elements typisiert bereitstellt. Anders als bei getComputedStyle() erhältst du keine Zeichenketten, sondern Objekte wie CSSUnitValue (mit value und unit) oder CSSKeywordValue. Damit lassen sich Werte ohne fehleranfälliges Zerlegen von Strings weiterverarbeiten.

values() ist nützlich, wenn dich nur die Werte interessieren. Brauchst du zusätzlich den Eigenschaftsnamen, nimm entries() oder iteriere direkt mit for...of über die Map (entspricht entries()). Für die Namen allein gibt es keys().

Rückgabewert

Typ

Iterator<CSSStyleValue[]>

Beschreibung

Ein neuer Iterator. Jeder Schritt liefert ein Array mit einem oder mehreren CSSStyleValue-Objekten, jeweils für eine Eigenschaft der Map.

Beispiele

Berechnete Stilwerte eines Elements durchlaufen

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

// Nur die ersten 5 Werte ausgeben
let i = 0;
for (const values of styleMap.values()) {
  console.log(values.map((v) => v.toString()));
  if (++i === 5) break;
}

["none"] ["auto"] ["normal"] ["normal"] ["auto"] (Konkrete Werte hängen vom Browser und vom Element ab)

values() mit keys() kombinieren

const box = document.querySelector('.box');
const map = box.computedStyleMap();

const keys = [...map.keys()];
const values = [...map.values()];

const index = keys.indexOf('width');
console.log(keys[index], values[index][0]);
// Einfacher geht es hier natürlich mit map.get('width')

width CSSUnitValue {value: 200, unit: "px"}

Alle Längenangaben in Pixeln herausfiltern

const el = document.querySelector('#card');
const pxValues = [...el.computedStyleMap().values()]
  .flat()
  .filter((v) => v instanceof CSSUnitValue && v.unit === 'px')
  .map((v) => v.value);

console.log(`${pxValues.length} Pixelwerte gefunden`, pxValues.slice(0, 5));

42 Pixelwerte gefunden [0, 0, 16, 300, 24]

Feature-Erkennung vor der Nutzung

const el = document.body;

if ('computedStyleMap' in el) {
  const count = [...el.computedStyleMap().values()].length;
  console.log(`Typed OM verfügbar, ${count} Eigenschaften`);
} else {
  // Fallback auf die String-basierte API
  const cs = getComputedStyle(el);
  console.log(`Fallback: ${cs.length} Eigenschaften`);
}

Typed OM verfügbar, 350 Eigenschaften

// Wichtig · Fallstricke

Browser-Unterstützung: 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 also vorher, ob 'computedStyleMap' in element gilt, und sieh einen Fallback über getComputedStyle() vor.
Jeder Wert ist ein Array, auch wenn die Eigenschaft nur einen Wert hat. Greife daher mit values[0] zu oder nutze .flat().
Der Iterator lässt sich nur einmal durchlaufen. Wenn du die Werte mehrfach brauchst, wandle sie mit [...map.values()] oder Array.from() in ein Array um.
Die Map ist schreibgeschützt. Zum Ändern von Stilen nimmst du element.attributeStyleMap (eine StylePropertyMap) mit set().
computedStyleMap() gibt eine Momentaufnahme mit vielen Hundert Eigenschaften zurück, auch Custom Properties. Das komplett zu durchlaufen kostet Zeit. Für einzelne Eigenschaften ist get() deutlich schneller.
Die Reihenfolge der Einträge legt der Browser fest (in der Regel alphabetisch, Custom Properties am Ende). Verlass dich nicht auf bestimmte Positionen.

Siehe auch

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