CSSValueList — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSValueList extends CSSValue

Beschreibung

CSSValueList erbt von CSSValue und steht für eine geordnete Sammlung von CSS-Werten. Ein solches Objekt bekam man, wenn CSSStyleDeclaration.getPropertyCSSValue() für eine Eigenschaft mit mehreren Werten aufgerufen wurde, zum Beispiel für font-family: Arial, sans-serif oder margin: 1px 2px. Die Eigenschaft cssValueType hatte dann den Wert CSSValue.CSS_VALUE_LIST (2).

Das Interface stellt zwei Mitglieder bereit:

length – nur lesbar, die Anzahl der Werte in der Liste.
item(index) – gibt den CSSValue an der angegebenen Position zurück oder null, wenn der Index außerhalb der Liste liegt.

Von CSSValue übernimmt es zusätzlich cssText und cssValueType. Die Einträge sind meist vom Typ CSSPrimitiveValue.

Wichtig: Das gesamte CSSValue-Modell ist veraltet und in aktuellen Browsern nicht mehr verfügbar. Für neuen Code solltest du stattdessen das CSS Typed Object Model nutzen (element.computedStyleMap(), StylePropertyMap.getAll(), CSSStyleValue.parseAll()) oder auf die Zeichenketten von getComputedStyle() zurückgreifen und diese selbst zerlegen.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Parameter von `item(index)`: nullbasierte Position des gewünschten Werts. Liegt der Index außerhalb von `0 … length - 1`, wird `null` zurückgegeben.

Beispiele

Historische Nutzung mit Feature-Erkennung

const el = document.body;
const style = getComputedStyle(el);

if (typeof style.getPropertyCSSValue === 'function') {
  // Altes DOM-Level-2-Style-Modell (nur sehr alte Browser)
  const list = style.getPropertyCSSValue('font-family');
  if (list && list.cssValueType === 2 /* CSS_VALUE_LIST */) {
    for (let i = 0; i < list.length; i++) {
      console.log(i, list.item(i).cssText);
    }
  }
} else {
  console.log('CSSValueList wird nicht unterstützt');
}

CSSValueList wird nicht unterstützt

Moderner Ersatz: CSS Typed OM mit computedStyleMap()

const box = document.createElement('div');
box.style.transitionProperty = 'opacity, transform';
document.body.append(box);

if ('computedStyleMap' in Element.prototype) {
  // getAll() liefert ein Array von CSSStyleValue-Objekten
  const werte = box.computedStyleMap().getAll('transition-property');
  console.log(werte.map((v) => v.toString()));
}

["opacity", "transform"]

Browserübergreifender Fallback über getComputedStyle()

const schriftListe = (element) =>
  getComputedStyle(element)
    .fontFamily
    .split(',')
    .map((name) => name.trim().replace(/^["']|["']$/g, ''));

document.body.style.fontFamily = '"Open Sans", Arial, sans-serif';
console.log(schriftListe(document.body));

["Open Sans", "Arial", "sans-serif"]

// Wichtig · Fallstricke

Veraltet: CSSValueList, CSSValue, CSSPrimitiveValue und getPropertyCSSValue() stehen in keinem aktuellen Standard mehr. Chrome und Firefox (ab Version 62) haben sie entfernt, auch in anderen modernen Engines solltest du nicht mit ihnen rechnen. Vorhandenen Code immer mit Feature-Erkennung absichern.
Nicht jede mehrwertige Eigenschaft ergab eine CSSValueList. Kurzschreibweisen wie margin gaben oft null zurück. Frag besser die Einzel-Eigenschaften ab (margin-top usw.).
Das naive Zerlegen von Zeichenketten wie im Fallback-Beispiel scheitert bei Kommas innerhalb von Funktionen (z. B. rgb(0, 0, 0) in box-shadow). Für so etwas ist CSSStyleValue.parseAll() aus dem Typed OM die robustere Lösung. Beachte dabei, dass das Typed OM in Firefox erst seit neueren Versionen unterstützt wird.
Die Liste ist eine Momentaufnahme. Spätere Stiländerungen tauchen in einem bereits abgerufenen Objekt nicht auf.

Siehe auch

CSSRuleList CSSValue FileList CSSMathClamp CSSMathMin