MediaList.mediaText — Eigenschaft · JavaScript-Referenz

Signatur

MediaList.mediaText

Beschreibung

Die Eigenschaft mediaText der Schnittstelle MediaList liefert alle Medienabfragen der Liste als einen einzigen, kommagetrennten String. Sie ist zugleich der Stringifier der Schnittstelle: String(mediaList) oder Template-Literale geben denselben Wert zurück.

Die Eigenschaft ist beschreibbar. Wenn man ihr einen neuen String zuweist, wird die Liste komplett geleert und aus dem neuen Text neu aufgebaut. Der Browser wendet die Änderung sofort an: Ein Stylesheet mit geändertem Medium wird je nach Treffer aktiviert oder deaktiviert. Für einzelne Einträge sind appendMedium() und deleteMedium() besser geeignet.

Typische Einsatzorte sind CSSStyleSheet.media (Medienliste eines <link>- oder <style>-Stylesheets), CSSMediaRule.media (eine @media-Regel) und CSSImportRule.media. So lassen sich z. B. Druck-Stylesheets zur Laufzeit umschalten oder Breakpoints dynamisch anpassen.

Der zurückgegebene Text ist serialisiert. Der Browser normalisiert also Leerzeichen und Schreibweise, deshalb kann er vom ursprünglich geschriebenen CSS abweichen.

Parameter

Name	Typ	Default	Beschreibung
$value (beim Setzen)	string		Neue, kommagetrennte Liste von Medienabfragen, z. B. `"screen and (max-width: 800px), print"`. Ein leerer String leert die Liste. Dann gilt das Stylesheet für alle Medien.

Rückgabewert

Typ

string

Beschreibung

Serialisierte Textform aller Medienabfragen der Liste, getrennt durch ", ". Ist die Liste leer, wird ein leerer String zurückgegeben.

Beispiele

Medienliste eines Stylesheets auslesen

// <link rel="stylesheet" href="print.css" media="print, screen and (max-width: 600px)">
const sheet = document.styleSheets[0];
console.log(sheet.media.mediaText);
console.log(`${sheet.media}`); // Stringifier liefert denselben Wert

print, screen and (max-width: 600px) print, screen and (max-width: 600px)

Druckansicht per Knopfdruck am Bildschirm simulieren

const printSheet = [...document.styleSheets]
  .find((s) => s.media.mediaText.includes('print'));

const toggle = document.querySelector('#preview-print');
let preview = false;

toggle.addEventListener('click', () => {
  preview = !preview;
  // Gesamte Liste ersetzen
  printSheet.media.mediaText = preview ? 'all' : 'print';
  console.log('Aktiv für:', printSheet.media.mediaText);
});

Aktiv für: all

Breakpoint einer @media-Regel dynamisch ändern

const style = document.createElement('style');
style.textContent = '@media (min-width: 768px) { .sidebar { display: block; } }';
document.head.append(style);

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

console.log(rule.media.mediaText);
rule.media.mediaText = '(min-width: 1024px)';
console.log(rule.conditionText);

(min-width: 768px) (min-width: 1024px)

Liste leeren und neu aufbauen

const media = document.styleSheets[0].media;
media.mediaText = '';
console.log(media.length, JSON.stringify(media.mediaText));

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

0 "" screen, print

// Wichtig · Fallstricke

Überschreiben statt Ergänzen: Eine Zuweisung ersetzt die gesamte Liste. Einzelne Einträge fügt man mit appendMedium() hinzu und entfernt sie mit deleteMedium().
Normalisierung: Der gelesene Wert ist serialisiert. Zum Beispiel wird SCREEN AND (MIN-WIDTH:600PX) zu screen and (min-width: 600px). Vergleicht man Strings direkt, führt das leicht zu Fehlern.
Ungültige Abfragen: Laut Spezifikation wird eine syntaktisch ungültige Abfrage zu not all. Es wird kein Fehler geworfen. Ältere Browser verhielten sich hier teils anders und warfen einen SyntaxError.
Cross-Origin-Stylesheets: Auf cssRules fremder Stylesheets ohne CORS-Freigabe kann man nicht zugreifen (SecurityError). sheet.media selbst bleibt aber lesbar.
Das media-Attribut des <link>- oder <style>-Elements bleibt mit mediaText synchron. Alternativ kann man also element.media setzen.
Um nur zu prüfen, ob eine Abfrage aktuell zutrifft, ist window.matchMedia() die richtige API, nicht MediaList.
Die Eigenschaft wird in allen modernen Browsern seit Langem unterstützt.

Siehe auch

MediaList.length MediaQueryList.media EditContext.text MediaError.message MediaStream.id