MediaList.deleteMedium() — Methode · JavaScript-Referenz

Signatur

MediaList.prototype.deleteMedium(oldMedium)

Beschreibung

Mit deleteMedium() entfernen Sie per CSSOM eine einzelne Medienabfrage aus einer MediaList. Solche Listen finden Sie unter anderem in CSSStyleSheet.media (entspricht dem media-Attribut von <style> bzw. <link>), in CSSMediaRule.media (die Bedingung einer @media-Regel) und in CSSImportRule.media.

Die Methode passt die Bedingungen eines Stylesheets zur Laufzeit an, ohne dass Sie die Zeichenkette mediaText selbst zerlegen und wieder zusammensetzen müssen. Ein typischer Fall ist ein Stylesheet mit media="screen, print", das künftig nur noch am Bildschirm gelten soll.

Das Argument wird als Medienabfrage eingelesen und mit den vorhandenen Einträgen in ihrer normalisierten (serialisierten) Form verglichen. Alle passenden Einträge werden entfernt. Gibt es keinen passenden Eintrag, löst die Methode eine DOMException vom Typ NotFoundError aus.

Parameter

Name	Typ	Default	Beschreibung
$oldMedium Pflicht	string		Die Medienabfrage, die entfernt werden soll, z. B. `"print"` oder `"(max-width: 600px)"`. Sie wird vor dem Vergleich normalisiert.

Beispiele

„print“ aus dem media-Attribut eines Stylesheets entfernen

// <style id="theme" media="screen, print">body { color: navy; }</style>
const sheet = document.getElementById('theme').sheet;

console.log(sheet.media.mediaText);
sheet.media.deleteMedium('print');
console.log(sheet.media.mediaText);
console.log(sheet.media.length);

screen, print screen 1

Medienabfrage in einem konstruierten Stylesheet ändern

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

// Stylesheet soll nur noch vom Farbschema abhängen
sheet.media.deleteMedium('screen');
console.log(sheet.media.mediaText);

(prefers-color-scheme: dark)

Sicher entfernen, ohne dass ein NotFoundError auftritt

const removeMedium = (mediaList, medium) => {
  try {
    mediaList.deleteMedium(medium);
    return true;
  } catch (err) {
    if (err.name === 'NotFoundError') return false;
    throw err;
  }
};

// Erste @media-Regel im ersten Stylesheet suchen
const rule = [...document.styleSheets[0].cssRules]
  .find((r) => r instanceof CSSMediaRule);

if (rule) {
  console.log(removeMedium(rule.media, 'print'));      // vorhanden
  console.log(removeMedium(rule.media, 'projection')); // nicht vorhanden
}

true false

// Wichtig · Fallstricke

NotFoundError: Ist die Medienabfrage nicht in der Liste enthalten, wirft die Methode eine DOMException (NotFoundError). Prüfen Sie vorher mit einer Schleife über die Liste bzw. mit mediaList.item(i), oder fangen Sie den Fehler mit try/catch ab.
Vergleich in normalisierter Form: Verglichen wird die serialisierte Schreibweise, nicht der Originaltext. So wird "(MAX-WIDTH:600px)" in der Regel als "(max-width: 600px)" erkannt. Bei ungewöhnlichen oder ungültigen Schreibweisen kann sich das Ergebnis je nach Browser unterscheiden.
Leere Liste: Wenn Sie den letzten Eintrag entfernen, ist die Liste leer. Eine leere MediaList bedeutet „alle Medien“: Das Stylesheet oder die Regel gilt danach also immer und nicht etwa nie.
Soll die gesamte Liste ersetzt werden, ist es einfacher, mediaList.mediaText direkt zu setzen.
Bei Stylesheets von fremden Ursprüngen (Cross-Origin ohne CORS) können Sie wegen der Sicherheitsbeschränkungen nicht auf cssRules zugreifen, sodass Sie die Medienlisten von @media-Regeln dort nicht ändern können.
Die Methode wird von allen modernen Browsern unterstützt. Ältere Implementierungen haben bei fehlenden Einträgen teils anders reagiert.

Siehe auch

MediaList.appendMedium() MediaList.item() MediaList.toString() Headers.delete() Highlight.delete()