CSSImportRule.supportsText — Eigenschaft · JavaScript-Referenz

Signatur

CSSImportRule.supportsText

Beschreibung

Die schreibgeschützte Eigenschaft supportsText der Schnittstelle CSSImportRule liefert den Text der Bedingung, die in einer @import-Regel mit supports() angegeben ist. So steht bei @import url("grid.css") supports(display: grid); in supportsText der Wert "display: grid". Die umschließende Funktion supports( … ) gehört nicht zum Rückgabewert.

Mit einer solchen bedingten @import-Regel lädt der Browser ein Stylesheet nur dann, wenn er die angegebene Eigenschaft bzw. den Selektor unterstützt. Die Bedingung folgt derselben Syntax wie bei @supports, also z. B. (display: grid) and (gap: 1rem) oder selector(:has(a)).

Die Eigenschaft hilft vor allem beim Untersuchen von Stylesheets per Skript, etwa in Entwicklerwerkzeugen, CSS-Analysetools oder beim Debuggen: Man sieht damit, welche Importe an Bedingungen geknüpft sind. Ob die Bedingung im aktuellen Browser erfüllt ist, sagt supportsText nicht. Dafür nimmt man CSS.supports().

Rückgabewert

Typ

string | null

Beschreibung

Der Text der Bedingung ohne die Klammer supports( … ). null, wenn die @import-Regel keine supports()-Bedingung hat.

Beispiele

Bedingung einer @import-Regel auslesen

// Stylesheet mit bedingtem Import anlegen
const style = document.createElement('style');
style.textContent = '@import url("grid.css") supports(display: grid);';
document.head.append(style);

const rule = style.sheet.cssRules[0];
console.log(rule instanceof CSSImportRule); // true
console.log(rule.supportsText);

true display: grid

Import ohne supports() liefert null

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

const rule = style.sheet.cssRules[0];
console.log(rule.supportsText);

null

Alle bedingten Importe auflisten und mit CSS.supports() prüfen

const listConditionalImports = () => {
  const result = [];
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // kann bei fremden Ursprüngen fehlschlagen
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (rule instanceof CSSImportRule && rule.supportsText) {
        result.push({
          href: rule.href,
          bedingung: rule.supportsText,
          erfuellt: CSS.supports(rule.supportsText)
        });
      }
    }
  }
  return result;
};

console.table(listConditionalImports());

Tabelle mit href, bedingung und erfuellt für jede bedingte @import-Regel

// Wichtig · Fallstricke

Browser-Kompatibilität: supports() in @import und damit auch supportsText sind relativ neu (Firefox ab 115, in Chromium und Safari erst in neueren Versionen). In älteren Browsern ist die Eigenschaft undefined. Davor schützt eine Prüfung wie 'supportsText' in CSSImportRule.prototype.
Ältere Browser, die supports() in @import nicht kennen, verwerfen die ganze Regel als ungültig. Sie taucht dann gar nicht in cssRules auf.
Die Eigenschaft ist schreibgeschützt. Wer ihr einen Wert zuweist, ändert nichts, im Strict Mode gibt es einen TypeError.
Der Wert kann gegenüber dem Quelltext normalisiert sein (Leerzeichen, Groß- und Kleinschreibung). Daher besser nicht exakt mit dem Original-String vergleichen.
Ob die Bedingung zutrifft, verrät supportsText nicht. Dafür gibt es CSS.supports().
Bei Stylesheets von fremden Ursprüngen ohne CORS löst der Zugriff auf cssRules einen SecurityError aus.

Siehe auch

CSS.supports() CSSImportRule.layerName CSSImportRule.styleSheet CSSImportRule.href CSSImportRule.media