CSSContainerRule.conditions — Eigenschaft · JavaScript-Referenz

Signatur

CSSContainerRule.conditions

Beschreibung

Die Eigenschaft conditions einer CSSContainerRule gibt die Bedingungen der zugehörigen CSS-Regel @container als Array zurück. Jeder Eintrag steht für eine Containerbedingung und hat zwei Eigenschaften: name (der Containername oder ein leerer String, wenn kein Name angegeben ist) und query (die Containerabfrage als serialisierter String, z. B. (width > 400px)).

Das ist vor allem wichtig, weil eine @container-Regel nach neuerer Spezifikation (CSS Conditional Rules Level 5) mehrere durch Komma getrennte Bedingungen enthalten kann, etwa @container card (width > 400px), sidebar (orientation: portrait). Die älteren Eigenschaften containerName und containerQuery geben jeweils nur einen einzigen String zurück. conditions dagegen legt jede Bedingung einzeln und bereits zerlegt offen.

Typische Einsatzfälle sind Werkzeuge, die Stylesheets auswerten: Entwicklerwerkzeuge, Linter, Tools zur Auswertung von Design-Systemen oder Skripte, die prüfen, welche Container-Namen in einem Stylesheet vorkommen. Die Eigenschaft ist schreibgeschützt. Wer die Bedingungen ändern will, muss die Regel entfernen und mit CSSStyleSheet.insertRule() neu anlegen.

Rückgabewert

Typ

Array<{ name: string, query: string }>

Beschreibung

Ein Array von Objekten, eines pro Containerbedingung. name enthält den Containernamen (oder ""), query die serialisierte Abfrage (oder "", wenn nur ein Name angegeben ist).

Beispiele

Bedingungen einer @container-Regel auslesen

const style = document.createElement('style');
style.textContent = `
  @container card (width > 400px), sidebar (orientation: portrait) {
    .title { font-size: 1.5rem; }
  }
`;
document.head.append(style);

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

if (rule instanceof CSSContainerRule && 'conditions' in rule) {
  for (const { name, query } of rule.conditions) {
    console.log(`Name: "${name}", Abfrage: ${query}`);
  }
} else {
  console.log('conditions wird nicht unterstützt');
}

Name: "card", Abfrage: (width > 400px) Name: "sidebar", Abfrage: (orientation: portrait)

Alle verwendeten Containernamen im Dokument sammeln

const collectContainerNames = () => {
  const names = new Set();

  const walk = (rules) => {
    for (const rule of rules) {
      if (rule instanceof CSSContainerRule) {
        const conds = rule.conditions
          ?? [{ name: rule.containerName, query: rule.containerQuery }];
        conds.forEach(({ name }) => name && names.add(name));
      }
      // Verschachtelte Regeln (@media, @supports, @layer …) durchlaufen
      if (rule.cssRules) walk(rule.cssRules);
    }
  };

  for (const sheet of document.styleSheets) {
    try {
      walk(sheet.cssRules);
    } catch {
      // Fremd-Stylesheets ohne CORS lösen einen SecurityError aus
    }
  }
  return [...names];
};

console.log(collectContainerNames());

["card", "sidebar"]

Unbenannte Bedingung und Vergleich mit containerQuery

const sheet = new CSSStyleSheet();
sheet.replaceSync('@container (min-width: 30em) { p { color: teal; } }');

const rule = sheet.cssRules[0];
console.log(rule.containerQuery);
console.log(rule.conditions?.[0]);

(min-width: 30em) { name: "", query: "(min-width: 30em)" }

// Wichtig · Fallstricke

Browser-Unterstützung: conditions ist neu und bisher nicht überall verfügbar, vor allem nicht in älteren Versionen von Firefox und Safari. Prüfe vor der Nutzung mit 'conditions' in rule und greife sonst auf containerName/containerQuery zurück.
Auch mehrere, durch Komma getrennte Bedingungen in @container werden nicht von allen Browsern unterstützt. Ältere Engines verwerfen solche Regeln unter Umständen ganz, dann taucht die Regel gar nicht in cssRules auf.
Der Wert in query ist serialisiert: Leerzeichen und Schreibweise können vom Quelltext abweichen. Vergleiche Abfragen daher nicht Zeichen für Zeichen mit dem ursprünglichen CSS.
Die Eigenschaft ist schreibgeschützt. Neue Werte zuzuweisen hat keine Wirkung (im Strict Mode kann ein TypeError auftreten).
Beim Zugriff auf cssRules von Stylesheets anderer Herkunft ohne passende CORS-Header wird ein SecurityError ausgelöst.

Siehe auch

CSSConditionRule.conditionText CSSContainerRule.containerName CSSContainerRule.containerQuery CSSFontFaceRule.style CSSGroupingRule.cssRules