CSSImportRule.media — Eigenschaft · JavaScript-Referenz

Signatur

CSSImportRule.media

Beschreibung

Die Eigenschaft media einer CSSImportRule liefert die Liste der Medienabfragen, die in der @import-Regel hinter der URL stehen, z. B. @import url("print.css") print;. Das zurückgegebene MediaList-Objekt ist „live“: Änderungen daran wirken sich direkt auf die Regel und damit auf die Gültigkeit der importierten Stilvorlage aus.

Die Eigenschaft selbst ist schreibgeschützt in dem Sinne, dass kein anderes MediaList-Objekt zugewiesen werden kann. Eine Zuweisung eines Strings wird jedoch laut Spezifikation ([PutForwards=mediaText]) an media.mediaText weitergeleitet – rule.media = "screen" ersetzt also die Medienabfrage.

Typische Einsatzfälle sind Werkzeuge, die Stilvorlagen analysieren (etwa um herauszufinden, welche Importe nur für den Druck gelten), sowie das dynamische Umschalten von Importen zur Laufzeit über appendMedium(), deleteMedium() oder mediaText.

Enthält die @import-Regel keine Medienabfrage, ist die Liste leer (length === 0, mediaText === "") – die importierte Stilvorlage gilt dann für alle Medien.

Rückgabewert

Typ

MediaList

Beschreibung

Live-MediaList mit den Medienabfragen der @import-Regel; leer, wenn keine angegeben wurden.

Beispiele

Medienabfragen einer @import-Regel auslesen

const style = document.createElement('style');
style.textContent = '@import url("print.css") print, screen and (max-width: 600px);';
document.head.append(style);

const rule = style.sheet.cssRules[0]; // CSSImportRule
console.log(rule.href);
console.log(rule.media.mediaText);
console.log(rule.media.length);
console.log(rule.media.item(0));

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

Medienliste zur Laufzeit ändern

const style = document.createElement('style');
style.textContent = '@import url("theme.css") screen;';
document.head.append(style);

const rule = style.sheet.cssRules[0];
rule.media.appendMedium('print');
console.log(rule.media.mediaText);

rule.media.deleteMedium('screen');
console.log(rule.media.mediaText);

// String-Zuweisung wird an mediaText weitergeleitet
rule.media = 'all';
console.log(rule.media.mediaText);

screen, print print all

Alle Importe des Dokuments mit ihren Medien auflisten

const listImports = () => {
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules;
    } catch {
      console.warn('Kein Zugriff (Cross-Origin):', sheet.href);
      continue;
    }
    for (const rule of rules) {
      if (rule instanceof CSSImportRule) {
        const media = rule.media.mediaText || 'alle Medien';
        console.log(`${rule.href} → ${media}`);
      }
    }
  }
};

listImports();

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

// Wichtig · Fallstricke

Cross-Origin: Der Zugriff auf cssRules einer Stilvorlage von einer fremden Origin ohne passende CORS-Header löst einen SecurityError aus – deshalb immer mit try…catch absichern.
Konstruierbare Stilvorlagen: In new CSSStyleSheet() sind @import-Regeln nicht erlaubt; replace()/replaceSync() ignorieren sie, insertRule() wirft einen Fehler. Beispiele daher mit einem <style>-Element testen.
Ungültige Medienabfragen werden beim Parsen zu not all normalisiert; mediaText kann also vom Quelltext abweichen.
deleteMedium() wirft einen NotFoundError, wenn der angegebene Eintrag nicht in der Liste steht.
Für die ebenfalls möglichen Zusätze layer() und supports() gibt es die eigenen Eigenschaften layerName und supportsText (neuere Browser).
Die Eigenschaft wird von allen aktuellen Browsern unterstützt.

Siehe auch

CSSImportRule.layerName CSSImportRule.href CSSImportRule.styleSheet CSSImportRule.supportsText CSSMediaRule.media