CSSContainerRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSContainerRule extends CSSConditionRule

Beschreibung

CSSContainerRule ist die CSSOM-Darstellung einer @container-At-Regel, also einer Container-Abfrage (Container Query). Solche Regeln wenden Stile abhängig von der Größe oder dem Zustand eines Vorfahren-Elements an, das mit container-type bzw. der Kurzschreibweise container als Abfrage-Container festgelegt wurde. Die Größe des Viewports spielt dabei keine Rolle.

Das Interface erbt von CSSConditionRule und damit von CSSGroupingRule und CSSRule. Neben den geerbten Mitgliedern conditionText, cssRules, insertRule() und deleteRule() bietet es zwei eigene, schreibgeschützte Eigenschaften:

containerName: der Name des abgefragten Containers, z. B. "karte", oder ein leerer String, wenn die Regel keinen Namen angibt.
containerQuery: nur die eigentliche Bedingung, z. B. "(min-width: 400px)".

Du begegnest dem Interface, wenn du Stylesheets zur Laufzeit untersuchst (etwa in Entwicklerwerkzeugen, Linting oder beim Testen von Designsystemen) oder @container-Regeln per insertRule() dynamisch anlegst und danach ihre Unterregeln bearbeitest. Einen Konstruktor gibt es nicht. Instanzen entstehen nur, wenn der Browser CSS parst, also über cssRules eines CSSStyleSheet.

Parameter

Name	Typ	Default	Beschreibung
$containerName	string	""	Schreibgeschützt. Name des Containers aus der `@container`-Regel; ein leerer String, wenn kein Name angegeben ist.
$containerQuery	string		Schreibgeschützt. Serialisierte Container-Bedingung ohne Namen, z. B. `(min-width: 400px)`.
$conditionText	string		Geerbt von `CSSConditionRule`. Die vollständige Bedingung einschließlich Name, z. B. `karte (min-width: 400px)`.
$cssRules	CSSRuleList		Geerbt von `CSSGroupingRule`. Eine Live-Liste der Regeln innerhalb des `@container`-Blocks.

Rückgabewert

Typ

CSSContainerRule

Beschreibung

Instanzen erhältst du über CSSStyleSheet.cssRules oder CSSGroupingRule.cssRules. Mit rule instanceof CSSContainerRule erkennst du sie.

Beispiele

Container-Regel auslesen (Constructable Stylesheet)

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  .card-wrapper { container: karte / inline-size; }
  @container karte (min-width: 400px) {
    .card { display: grid; grid-template-columns: 1fr 2fr; }
  }
`);

const rule = [...sheet.cssRules].find((r) => r instanceof CSSContainerRule);

console.log(rule.containerName);
console.log(rule.containerQuery);
console.log(rule.conditionText);
console.log(rule.cssRules[0].selectorText);

karte (min-width: 400px) karte (min-width: 400px) .card

@container-Regel dynamisch einfügen und erweitern

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

sheet.insertRule('.sidebar { container-type: inline-size; }');
const index = sheet.insertRule(
  '@container (width > 300px) { .nav { flex-direction: row; } }',
  sheet.cssRules.length
);

const containerRule = sheet.cssRules[index];
// Unterregel innerhalb des @container-Blocks ergänzen
containerRule.insertRule('.nav a { padding: 1rem; }', containerRule.cssRules.length);

console.log(containerRule.containerName === '');
console.log(containerRule.cssRules.length);

true 2

Alle Container-Abfragen der Seite sammeln (rekursiv, CORS-sicher)

const collectContainerRules = (rules, result = []) => {
  for (const rule of rules) {
    if (rule instanceof CSSContainerRule) {
      result.push({ name: rule.containerName || '(unbenannt)', query: rule.containerQuery });
    }
    // Verschachtelte Gruppen (@media, @supports, @layer …) durchsuchen
    if (rule.cssRules) collectContainerRules(rule.cssRules, result);
  }
  return result;
};

const all = [];
for (const sheet of document.styleSheets) {
  try {
    collectContainerRules(sheet.cssRules, all);
  } catch (err) {
    // Fremd-Origin-Stylesheets ohne CORS werfen SecurityError
    console.warn('Übersprungen:', sheet.href);
  }
}
console.table(all);

// Wichtig · Fallstricke

Kein Konstruktor: new CSSContainerRule() wirft einen TypeError. Regeln entstehen nur durch das Parsen von CSS, etwa über insertRule(), replaceSync() oder <style>.
Schreibgeschützt: containerName, containerQuery und conditionText lassen sich nicht ändern. Für eine neue Bedingung löschst du die Regel mit deleteRule() und fügst sie neu ein.
Serialisierung: Die Browser geben die Werte normalisiert zurück (Leerzeichen, Groß- und Kleinschreibung). Deshalb nicht auf exakte String-Gleichheit mit dem Quell-CSS setzen.
Cross-Origin: Wenn du cssRules eines fremden Stylesheets ohne CORS-Freigabe liest, wird ein SecurityError ausgelöst. Den Zugriff deshalb in try/catch kapseln.
Kompatibilität: Das Interface selbst gibt es ab Chrome 105, Safari 16 und Firefox 110. containerName und containerQuery kamen in Chromium erst mit Version 111 und in Safari mit 16.4 hinzu. Vorher nur conditionText verwenden oder per 'containerName' in CSSContainerRule.prototype prüfen, ob die Eigenschaft vorhanden ist.
Style-Queries wie @container style(--theme: dark) werden ebenfalls als CSSContainerRule dargestellt. Browser, die sie nicht unterstützen, verwerfen solche Regeln jedoch beim Parsen.

Siehe auch

CSSFontFaceRule CSSConditionRule CSSFunctionRule CSSGroupingRule CSSPageRule CSSViewTransitionRule