MediaList.appendMedium() — Methode · JavaScript-Referenz

Signatur

MediaList.prototype.appendMedium(medium)

Beschreibung

appendMedium() fügt eine einzelne Medienabfrage an das Ende einer MediaList an. Eine MediaList bekommt man in der Praxis über CSSStyleSheet.media (Medienliste eines ganzen Stylesheets bzw. eines <style>/<link>-Elements), über CSSMediaRule.media (Bedingung eines @media-Blocks) oder über CSSImportRule.media.

Mit der Methode lässt sich zur Laufzeit steuern, für welche Medien ein Stylesheet oder eine Regel gilt, z. B. um ein Druck-Stylesheet auch für den Bildschirm freizugeben oder einen @media-Block um eine weitere Bedingung zu erweitern. Die Einträge einer MediaList werden mit ODER verknüpft (wie Kommas in @media screen, print) – jede angehängte Abfrage erweitert also den Geltungsbereich.

Laut CSSOM-Spezifikation wird der übergebene Text als Medienabfrage geparst. Ist dieselbe (normalisierte) Abfrage bereits in der Liste enthalten, passiert nichts – Duplikate entstehen nicht. Nach dem Aufruf ändert sich mediaText entsprechend, und der Browser wertet die Styles sofort neu aus.

Parameter

Name	Typ	Default	Beschreibung
$medium Pflicht	string		Eine einzelne Medienabfrage als Zeichenkette, z. B. `"print"`, `"screen and (min-width: 800px)"` oder `"(prefers-color-scheme: dark)"`.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die MediaList wird direkt verändert.

Beispiele

Druck-Stylesheet zusätzlich für den Bildschirm aktivieren

// <style id="print-styles" media="print"> ... </style>
const styleEl = document.getElementById('print-styles');
const media = styleEl.sheet.media;

console.log(media.mediaText);
media.appendMedium('screen');
console.log(media.mediaText);
console.log(media.length);

print print, screen 2

@media-Regel zur Laufzeit erweitern

const style = document.createElement('style');
style.textContent = '@media (max-width: 600px) { body { font-size: 18px; } }';
document.head.append(style);

const rule = [...style.sheet.cssRules]
  .find((r) => r instanceof CSSMediaRule);

// Große Schrift auch im Druck verwenden
rule.media.appendMedium('print');
console.log(rule.conditionText ?? rule.media.mediaText);

(max-width: 600px), print

Duplikate werden ignoriert

const sheet = new CSSStyleSheet({ media: 'screen' });
sheet.media.appendMedium('screen');
sheet.media.appendMedium('print');

console.log([...sheet.media]);

["screen", "print"]

Vorschau-Schalter für Dark-Mode-Styles

// <link id="dark" rel="stylesheet" href="dark.css" media="(prefers-color-scheme: dark)">
const darkSheet = document.getElementById('dark').sheet;

const enableDarkPreview = () => {
  // 'all' lässt das Stylesheet unabhängig von der Systemeinstellung greifen
  darkSheet.media.appendMedium('all');
};

const disableDarkPreview = () => {
  darkSheet.media.deleteMedium('all');
};

document.querySelector('#preview-toggle')
  .addEventListener('change', (e) =>
    e.target.checked ? enableDarkPreview() : disableDarkPreview());

// Wichtig · Fallstricke

Nur eine Abfrage pro Aufruf: Eine kommagetrennte Liste wie "screen, print" ist hier nicht vorgesehen. Für mehrere Einträge rufst du die Methode mehrfach auf oder setzt mediaText direkt.
Ungültige Abfragen: Je nach Browser wird eine ungültige Abfrage stillschweigend verworfen oder als not all übernommen. Einen Fehler gibt es dabei normalerweise nicht, deshalb solltest du das Ergebnis über mediaText prüfen.
ODER-Logik: Mit dem Anhängen wird der Geltungsbereich größer, nicht kleiner. Wenn du einschränken willst, musst du die Abfrage selbst anpassen (z. B. "screen and (min-width: 800px)").
Zugriff auf fremde Stylesheets: Bei Stylesheets von anderen Ursprüngen ohne passende CORS-Header löst schon der Zugriff auf cssRules einen SecurityError aus. sheet.media selbst ist meist erreichbar.
Bei <link>/<style> wird das media-Attribut im DOM nicht in jedem Browser mitaktualisiert. Wenn du einen einheitlichen Zustand brauchst, setze stattdessen element.media.
Die Methode wird von allen modernen Browsern unterstützt. Konstruierbare Stylesheets (new CSSStyleSheet()) gibt es erst in neueren Browserversionen.

Siehe auch

MediaList.deleteMedium() MediaList.item() MediaList.toString() SVGPointList.appendItem() Element.append()