StyleSheet.media — Eigenschaft · JavaScript-Referenz

Signatur

StyleSheet.media

Beschreibung

Die schreibgeschützte Eigenschaft media der Schnittstelle StyleSheet (und damit auch von CSSStyleSheet) gibt ein MediaList-Objekt zurück. Es beschreibt, für welche Zielmedien bzw. Medienabfragen das Stylesheet gilt. Bei <link>- und <style>-Elementen wird die Liste aus dem HTML-Attribut media befüllt, bei @import-Regeln aus der dort angegebenen Medienliste.

„Schreibgeschützt“ heißt nur, dass die Referenz auf das MediaList-Objekt nicht ersetzt werden kann. Die Liste selbst lässt sich ändern: über mediaText, appendMedium() und deleteMedium(). Wenn du sheet.media einen String zuweist, wird er laut Spezifikation an media.mediaText weitergeleitet ([PutForwards=mediaText]).

Typische Anwendungsfälle sind: Stylesheets zur Laufzeit nur für bestimmte Medien aktivieren (etwa eine Druckvorschau auf dem Bildschirm), die Medienbedingungen eingebundener Stylesheets prüfen oder bei konstruierten Stylesheets (new CSSStyleSheet({ media })) eine Medienbedingung festlegen. Eine leere Liste bedeutet: Das Stylesheet gilt für alle Medien.

Rückgabewert

Typ

MediaList

Beschreibung

Ein Live-MediaList-Objekt mit den Eigenschaften mediaText und length sowie den Methoden item(), appendMedium() und deleteMedium(). Ist die Liste leer (length === 0), gilt das Stylesheet für alle Medien.

Beispiele

Medienbedingungen aller Stylesheets auflisten

// HTML: <link rel="stylesheet" href="main.css">
//       <link rel="stylesheet" href="print.css" media="print">
//       <style media="screen and (max-width: 600px)">…</style>
for (const sheet of document.styleSheets) {
  const { media } = sheet;
  const ziel = media.length === 0 ? 'alle Medien' : media.mediaText;
  console.log(`${sheet.href ?? 'inline'} → ${ziel}`);
}

https://example.com/main.css → alle Medien https://example.com/print.css → print inline → screen and (max-width: 600px)

Druckvorschau auf dem Bildschirm umschalten

const printSheet = [...document.styleSheets]
  .find((s) => s.href?.endsWith('print.css'));

const togglePrintPreview = (aktiv) => {
  if (!printSheet) return;
  if (aktiv) {
    printSheet.media.appendMedium('screen');
  } else {
    printSheet.media.deleteMedium('screen');
  }
  console.log('Medien:', printSheet.media.mediaText);
};

togglePrintPreview(true);
togglePrintPreview(false);

Medien: print, screen Medien: print

Konstruiertes Stylesheet mit Medienbedingung

const darkSheet = new CSSStyleSheet({ media: '(prefers-color-scheme: dark)' });
darkSheet.replaceSync('body { background: #111; color: #eee; }');
document.adoptedStyleSheets = [...document.adoptedStyleSheets, darkSheet];

console.log(darkSheet.media.mediaText);

// Nachträglich per Zuweisung ändern (wird an mediaText weitergeleitet)
darkSheet.media = 'print';
console.log(darkSheet.media.mediaText, darkSheet.media.length);

(prefers-color-scheme: dark) print 1

// Wichtig · Fallstricke

Kein Ersetzen des Objekts: sheet.media liefert immer dasselbe MediaList-Objekt. Eine String-Zuweisung setzt nur mediaText. Willst du die Liste leeren, weise mediaText = '' zu, dann gilt das Stylesheet für alle Medien.
Attribut und Liste sind nicht dasselbe: Wenn du das media-Attribut eines <link>/<style>-Elements änderst, wird die Liste aktualisiert. Umgekehrt ändern Anpassungen per appendMedium() das HTML-Attribut nicht. Brauchst du beides synchron, setze lieber das Attribut.
Ungültige Abfragen: Syntaktisch fehlerhafte Medienabfragen werden zu not all und schalten das Stylesheet damit praktisch ab.
Cross-Origin: Anders als cssRules kannst du media auch bei Stylesheets von fremden Origins lesen, ohne dass ein SecurityError ausgelöst wird.
Kompatibilität: Die Eigenschaft wird in allen Browsern unterstützt. Die Option media im Konstruktor new CSSStyleSheet() und adoptedStyleSheets gibt es erst in neueren Browsern (Safari ab 16.4).
Ob eine Medienbedingung gerade zutrifft, verrät media nicht. Prüfe das mit window.matchMedia(sheet.media.mediaText).matches.

Siehe auch

StyleSheet CSSStyleSheet MediaList MediaList.mediaText MediaList.prototype.appendMedium() MediaList.prototype.deleteMedium() Window.prototype.matchMedia() Document.styleSheets StyleSheet.disabled