CSSRuleList.item() — Methode · JavaScript-Referenz

Signatur

CSSRuleList.prototype.item(index)

Beschreibung

Die Methode item() liefert eine einzelne CSS-Regel aus einer CSSRuleList. Solche Listen bekommt man vor allem über CSSStyleSheet.cssRules. Auch verschachtelte Regeln wie @media, @supports oder @layer stellen ihre Kindregeln über CSSGroupingRule.cssRules als solche Liste bereit.

Ein Aufruf von item(i) entspricht dem Zugriff mit eckigen Klammern list[i]. Der Unterschied liegt beim ungültigen Index: item() gibt dann null zurück, die Klammerschreibweise dagegen undefined. Mit item() lassen sich Stylesheets analysieren, bestimmte Regeln finden oder Styles zur Laufzeit prüfen, etwa beim Theming, beim Debuggen oder in Werkzeugen, die ungenutztes CSS aufspüren.

Die Liste ist live. Wenn Sie Regeln mit insertRule() oder deleteRule() einfügen oder entfernen, ändern sich length und die Indizes sofort. Das sollten Sie beim Durchlaufen in einer Schleife beachten.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nullbasierte Position der gewünschten Regel. Der Wert wird in eine vorzeichenlose 32-Bit-Ganzzahl umgewandelt (`unsigned long`). Zum Beispiel wird `-1` zu `4294967295` und liefert damit `null`.

Rückgabewert

Typ

CSSRule | null

Beschreibung

Die CSSRule an der angegebenen Position, zum Beispiel eine CSSStyleRule, CSSMediaRule oder CSSKeyframesRule. Ist index größer oder gleich length, wird null zurückgegeben.

Beispiele

Erste Regel eines Stylesheets auslesen

// Voraussetzung: <style>body { margin: 0; } h1 { color: teal; }</style>
const sheet = document.styleSheets[0];
const rules = sheet.cssRules;

const first = rules.item(0);
console.log(first.cssText);
console.log(rules.item(99)); // Index existiert nicht

body { margin: 0px; } null

Alle Regeln durchlaufen und nach Selektor suchen

const findRule = (sheet, selector) => {
  const rules = sheet.cssRules;
  for (let i = 0; i < rules.length; i++) {
    const rule = rules.item(i);
    if (rule instanceof CSSStyleRule && rule.selectorText === selector) {
      return rule;
    }
  }
  return null;
};

const h1Rule = findRule(document.styleSheets[0], 'h1');
if (h1Rule) {
  h1Rule.style.color = 'crimson'; // Regel direkt ändern
  console.log(h1Rule.cssText);
}

h1 { color: crimson; }

Verschachtelte @media-Regeln auswerten

const style = document.createElement('style');
style.textContent = `
  @media (max-width: 600px) {
    .nav { display: none; }
    .burger { display: block; }
  }`;
document.head.append(style);

const media = style.sheet.cssRules.item(0);
console.log(media.conditionText);
for (let i = 0; i < media.cssRules.length; i++) {
  console.log(media.cssRules.item(i).selectorText);
}

(max-width: 600px) .nav .burger

item() im Vergleich zur Klammerschreibweise

const rules = document.styleSheets[0].cssRules;
const outOfRange = rules.length + 5;

console.log(rules.item(outOfRange)); // null
console.log(rules[outOfRange]);      // undefined

// Moderne Alternative: in ein Array umwandeln
const selectors = Array.from(rules)
  .filter((r) => r instanceof CSSStyleRule)
  .map((r) => r.selectorText);
console.log(selectors);

null undefined ["body", "h1"]

// Wichtig · Fallstricke

CORS: Stylesheets, die von einem fremden Ursprung geladen werden, sind ohne passende CORS-Header (und crossorigin-Attribut) gesperrt. Schon der Zugriff auf sheet.cssRules wirft dann einen SecurityError, sodass item() gar nicht erst aufgerufen werden kann. Umschließen Sie den Zugriff daher mit try/catch.
Live-Liste: Wenn Sie in einer Schleife mit deleteRule(i) löschen, rücken die folgenden Indizes nach. Durchlaufen Sie die Liste in diesem Fall rückwärts.
Negative Indizes: item(-1) liefert nicht die letzte Regel, sondern null. Für die letzte Regel nutzen Sie item(rules.length - 1).
Kein Array: CSSRuleList ist iterierbar (for...of), hat aber keine Array-Methoden wie map oder filter. Wandeln Sie die Liste bei Bedarf mit Array.from() um.
Der Typ der zurückgegebenen Regel ist unterschiedlich. Prüfen Sie ihn mit instanceof (z. B. CSSStyleRule), bevor Sie auf selectorText oder style zugreifen.
Wird die Methode ohne Argument aufgerufen, wirft sie einen TypeError.

Siehe auch

CSSValueList.item() FileList.item() DOMRectList.item() NodeList.item() TouchList.item()