CSSSupportsRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSSupportsRule extends CSSConditionRule

Beschreibung

CSSSupportsRule ist die CSSOM-Darstellung einer @supports-Regel. Mit @supports gelten CSS-Regeln nur dann, wenn der Browser eine bestimmte Eigenschaft, einen Wert oder einen Selektor unterstützt, z. B. @supports (display: grid) { … }. Beim Parsen eines Stylesheets legt der Browser für jede solche Regel ein CSSSupportsRule-Objekt an. Du findest es in CSSStyleSheet.cssRules.

Die Vererbungskette lautet CSSRule → CSSGroupingRule → CSSConditionRule → CSSSupportsRule. Das Interface bringt keine eigenen Mitglieder mit, sondern nutzt die geerbten:

conditionText (von CSSConditionRule): die Bedingung als Zeichenkette, z. B. "(display: grid)".
cssRules (von CSSGroupingRule): eine CSSRuleList mit den verschachtelten Regeln.
insertRule(rule, index) und deleteRule(index): fügen verschachtelte Regeln ein oder entfernen sie.
cssText, parentRule, parentStyleSheet (von CSSRule): die ganze Regel als Text und ihr Kontext im Stylesheet.

Typische Einsatzfälle sind Werkzeuge, die Stylesheets untersuchen, z. B. um alle Feature-Weichen einer Seite aufzulisten. Ein weiterer Fall ist, zur Laufzeit Regeln in einen bestehenden @supports-Block einzufügen. Wenn du nur prüfen willst, ob der Browser ein Feature kann, nimmst du besser direkt CSS.supports().

Rückgabewert

Typ

CSSSupportsRule

Beschreibung

Du erzeugst Instanzen nicht selbst mit einem Konstruktor. Sie stehen in CSSStyleSheet.cssRules oder in CSSGroupingRule.cssRules.

Beispiele

Alle @supports-Regeln eines Dokuments auflisten

// Durchsucht alle gleichherkünftigen Stylesheets nach @supports-Regeln
const findSupportsRules = () => {
  const result = [];
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // wirft bei fremden Stylesheets (CORS) einen Fehler
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (rule instanceof CSSSupportsRule) {
        result.push({ bedingung: rule.conditionText, anzahl: rule.cssRules.length });
      }
    }
  }
  return result;
};

console.table(findSupportsRules());

┌─────────┬──────────────────────┬────────┐ │ (index) │ bedingung │ anzahl │ ├─────────┼──────────────────────┼────────┤ │ 0 │ '(display: grid)' │ 3 │ └─────────┴──────────────────────┴────────┘

@supports-Regel per insertRule anlegen und auslesen

const style = document.createElement('style');
document.head.append(style);
const sheet = style.sheet;

const index = sheet.insertRule(
  '@supports (backdrop-filter: blur(4px)) { .dialog { backdrop-filter: blur(4px); } }',
  0
);

const rule = sheet.cssRules[index];
console.log(rule instanceof CSSSupportsRule);
console.log(rule.conditionText);
console.log(rule.cssRules[0].selectorText);

true (backdrop-filter: blur(4px)) .dialog

Regeln in einen bestehenden @supports-Block einfügen und entfernen

const style = document.createElement('style');
style.textContent = '@supports (display: grid) { .layout { display: grid; } }';
document.head.append(style);

const supportsRule = style.sheet.cssRules[0];

// Verschachtelte Regel am Ende ergänzen
supportsRule.insertRule(
  '.layout { grid-template-columns: repeat(3, 1fr); }',
  supportsRule.cssRules.length
);
console.log(supportsRule.cssRules.length);

// Erste verschachtelte Regel wieder löschen
supportsRule.deleteRule(0);
console.log(supportsRule.cssText);

2 @supports (display: grid) { .layout { grid-template-columns: repeat(3, 1fr); } }

Gibt der Browser der Bedingung recht?

const [rule] = [...document.styleSheets[0].cssRules]
  .filter((r) => r instanceof CSSSupportsRule);

if (rule) {
  // CSS.supports() akzeptiert dieselbe Bedingungssyntax
  const aktiv = CSS.supports(rule.conditionText);
  console.log(`${rule.conditionText} → ${aktiv ? 'aktiv' : 'inaktiv'}`);
}

(display: grid) → aktiv

// Wichtig · Fallstricke

conditionText nur lesen: Nach aktueller Spezifikation ist conditionText schreibgeschützt. Ältere Browser erlaubten das Schreiben. Um die Bedingung zu ändern, löschst du die Regel mit deleteRule() und legst sie mit neuer Bedingung per insertRule() wieder an.
Normalisierung: Der Browser normalisiert conditionText und cssText, zum Beispiel Leerzeichen und Groß-/Kleinschreibung. Vergleiche mit dem Originaltext aus der Quelldatei können deshalb fehlschlagen.
CORS: Bei Stylesheets von einer anderen Herkunft ohne passende CORS-Header wirft der Zugriff auf cssRules einen SecurityError. Umschließe den Zugriff deshalb mit try/catch.
Typerkennung: Prüfe den Typ mit instanceof CSSSupportsRule. Die Konstante CSSRule.SUPPORTS_RULE (Wert 12) und die Eigenschaft rule.type sind veraltet.
Syntaxfehler: insertRule() wirft einen SyntaxError, wenn die Regel ungültig ist oder an dieser Stelle nicht erlaubt ist.
Kompatibilität: Alle modernen Browser unterstützen das Interface. Neuere Bedingungsformen wie selector() oder font-tech() hängen jedoch von der Browserversion ab.

Siehe auch

CSS.supports() CSSImportRule CSSPropertyRule CSSScopeRule CSSFunctionRule