CSSValueList.item() — Methode · JavaScript-Referenz

Signatur

CSSValueList.prototype.item(index)

Beschreibung

Die Methode item() der veralteten Schnittstelle CSSValueList liefert einen einzelnen Wert aus einer Liste von CSS-Werten, zum Beispiel einen Eintrag aus einer font-family-Liste oder eine einzelne Transformationsfunktion. Die Liste ist nullbasiert: Der erste Wert hat den Index 0, der letzte den Index length - 1.

An eine CSSValueList kam man früher über CSSStyleDeclaration.getPropertyCSSValue(), wenn eine Eigenschaft mehrere Werte enthielt. Alternativ zu item(i) funktionierte auch der Zugriff mit eckigen Klammern (list[i]). Jedes Element ist ein CSSValue, meist konkret ein CSSPrimitiveValue, dessen Inhalt man über cssText oder typisierte Methoden wie getStringValue() ausliest.

Die ganze API (CSSValue, CSSPrimitiveValue, CSSValueList) gehört zum alten DOM-Level-2-Style-Modell und wurde aus den Standards und den meisten Browsern entfernt. In neuem Code solltest du stattdessen das CSS Typed Object Model nutzen (element.computedStyleMap(), StylePropertyMap.getAll()) oder den Rückgabewert von getPropertyValue() als Zeichenkette auswerten.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nullbasierte Position des gewünschten Werts (`unsigned long`). Werte ab `length` liefern `null`.

Rückgabewert

Typ

CSSValue | null

Beschreibung

Der CSSValue an der Position index oder null, wenn der Index größer oder gleich length ist.

Beispiele

Alte API mit Feature-Erkennung verwenden

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

if (typeof style.getPropertyCSSValue === 'function') {
  const list = style.getPropertyCSSValue('font-family');
  // Nur Listen besitzen length und item()
  if (list && typeof list.item === 'function') {
    for (let i = 0; i < list.length; i++) {
      console.log(i, list.item(i).cssText);
    }
    console.log(list.item(list.length)); // außerhalb des Bereichs
  }
} else {
  console.log('CSSValueList wird von diesem Browser nicht unterstützt.');
}

CSSValueList wird von diesem Browser nicht unterstützt. // In alten Browsern z. B.: // 0 "Helvetica Neue" // 1 Arial // 2 sans-serif // null

Moderner Ersatz: font-family als Zeichenkette auswerten

const fontFamilies = (el) =>
  getComputedStyle(el)
    .getPropertyValue('font-family')
    .split(',')
    .map((f) => f.trim().replace(/^["']|["']$/g, ''));

const families = fontFamilies(document.body);
// Entspricht list.item(0)
console.log(families[0]);
console.log(families.at(-1));

Helvetica Neue sans-serif

Moderner Ersatz: CSS Typed OM für Transformationen

const box = document.createElement('div');
box.style.transform = 'translateX(10px) rotate(45deg)';
document.body.append(box);

if ('computedStyleMap' in Element.prototype) {
  const transform = box.attributeStyleMap.get('transform');
  // CSSTransformValue ist indexierbar wie früher die CSSValueList
  for (let i = 0; i < transform.length; i++) {
    console.log(i, transform[i].toString());
  }
}

0 translateX(10px) 1 rotate(45deg)

// Wichtig · Fallstricke

Veraltet und entfernt: CSSValueList und getPropertyCSSValue() stehen nicht mehr in aktuellen Spezifikationen. Firefox hat die API mit Version 62 entfernt, Chromium-Browser unterstützen sie schon lange nicht mehr. Verlass dich in Produktionscode nicht darauf.
Ein Index außerhalb des Bereichs wirft keinen Fehler, sondern liefert null. Prüfe den Rückgabewert, bevor du auf cssText zugreifst.
Nicht jeder CSSValue ist eine Liste: Einzelwerte sind CSSPrimitiveValue-Objekte ohne item(). Prüfe vorher cssValueType === CSSValue.CSS_VALUE_LIST oder ob item existiert.
Als Ersatz bietet sich das CSS Typed OM an (computedStyleMap(), StylePropertyMap.getAll()). Chromium und Safari unterstützen es, Firefox nur teilweise. Deshalb solltest du bei Bedarf auf getPropertyValue() und das Zerlegen der Zeichenkette zurückfallen.

Siehe auch

CSSRuleList.item() FileList.item() MediaList.item() NodeList.item() DOMRectList.item()