MediaList.item() — Methode · JavaScript-Referenz

Signatur

MediaList.prototype.item(index)

Beschreibung

Die Methode item() des MediaList-Interfaces liest eine einzelne Medienabfrage (z. B. "screen and (min-width: 600px)") aus der Liste. Eine MediaList kommt unter anderem über CSSMediaRule.media, CSSImportRule.media oder StyleSheet.media vor, also überall dort, wo ein Stylesheet oder eine Regel an Medienbedingungen geknüpft ist.

Die Liste ist nullbasiert: Gültige Indizes reichen von 0 bis mediaList.length - 1. Bei einem Index außerhalb dieses Bereichs wirft item() keinen Fehler, sondern gibt null zurück.

Statt item(i) kann man auch in Klammerschreibweise mediaList[i] zugreifen. Dort bekommt man bei ungültigem Index allerdings undefined statt null. Weil MediaList iterierbar ist, lassen sich außerdem for...of und Array.from() verwenden. Den gesamten Text der Liste liefert mediaList.mediaText.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nullbasierter Index der gewünschten Medienabfrage. Der Wert wird in eine vorzeichenlose 32-Bit-Ganzzahl umgewandelt (`unsigned long`).

Rückgabewert

Typ

string | null

Beschreibung

Die serialisierte Medienabfrage an der Position index oder null, wenn es den Index nicht gibt.

Beispiele

Medienabfragen eines Stylesheets auslesen

// Voraussetzung: <link rel="stylesheet" href="print.css" media="print, screen and (max-width: 600px)">
const sheet = document.styleSheets[0];
const media = sheet.media;

console.log(media.length);
console.log(media.item(0));
console.log(media.item(1));
console.log(media.item(5));

2 print screen and (max-width: 600px) null

Alle @media-Regeln eines Stylesheets auflisten

const style = document.createElement('style');
style.textContent = `
  @media screen and (min-width: 900px), print { body { font-size: 18px; } }
`;
document.head.append(style);

const [rule] = style.sheet.cssRules; // CSSMediaRule
for (let i = 0; i < rule.media.length; i++) {
  console.log(`Abfrage ${i}:`, rule.media.item(i));
}

Abfrage 0: screen and (min-width: 900px) Abfrage 1: print

Sicherer Zugriff mit Prüfung auf null

const style = document.createElement('style');
style.media = 'screen';
document.head.append(style);

const media = style.sheet.media;
media.appendMedium('print');

const getMedium = (list, i) => list.item(i) ?? '(nicht vorhanden)';

console.log(getMedium(media, 1));
console.log(getMedium(media, 3));
console.log(media[3]); // Klammerschreibweise liefert undefined

print (nicht vorhanden) undefined

// Wichtig · Fallstricke

null gegenüber undefined: item() gibt bei ungültigem Index null zurück, mediaList[i] dagegen undefined. Das ist wichtig bei strikten Vergleichen (===).
Negative Indizes zählen nicht vom Ende her wie bei Array.prototype.at(). item(-1) wird in eine sehr große Zahl umgewandelt und liefert null.
Der Aufruf ganz ohne Argument wirft einen TypeError.
Die zurückgegebenen Strings sind vom Browser serialisiert. Schreibweise und Leerzeichen können daher vom Original im CSS abweichen (z. B. Kleinschreibung, normalisierte Leerzeichen).
Beim Zugriff auf cssRules von Stylesheets anderer Herkunft (Cross-Origin) ohne CORS wirft der Browser einen SecurityError. sheet.media selbst ist davon nicht betroffen.
Die Methode wird von allen modernen Browsern unterstützt.

Siehe auch

MediaList.toString() MediaList.deleteMedium() MediaList.appendMedium() NodeList.item() FileList.item()