CSSLayerBlockRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSLayerBlockRule extends CSSGroupingRule

Beschreibung

CSSLayerBlockRule ist die CSSOM-Darstellung einer @layer-Blockregel. Mit solchen Regeln werden Stilregeln einer benannten oder anonymen Kaskadenebene (Cascade Layer) zugeordnet. Ebenen legen fest, welche Regeln gewinnen, und zwar unabhängig von der Spezifität: Später deklarierte Ebenen haben Vorrang vor früheren.

Das Interface erbt von CSSGroupingRule. Deshalb gibt es cssRules (die Regeln innerhalb des Blocks) sowie insertRule() und deleteRule(). Von CSSRule kommen außerdem cssText, parentRule und parentStyleSheet. Neu ist nur die schreibgeschützte Eigenschaft name. Sie enthält den Namen der Ebene, bei einer anonymen Ebene (@layer { … }) ist sie ein leerer String.

Typische Einsatzfälle: Stylesheets zur Laufzeit untersuchen (etwa in Entwicklerwerkzeugen oder Linter-Skripten), Regeln gezielt in eine bestimmte Ebene einfügen oder mit Constructable Stylesheets ebenenbasierte Designsysteme aufbauen.

Die reine Anweisungsform @layer a, b; ohne Block ist keine CSSLayerBlockRule. Sie wird als CSSLayerStatementRule mit der Eigenschaft nameList dargestellt.

Parameter

Name	Typ	Default	Beschreibung
$name	string		Schreibgeschützte Eigenschaft: der Name der Ebene, so wie er in der Regel steht (z. B. `"base"` oder `"framework.reset"`). Bei anonymen Ebenen ein leerer String.
$cssRules	CSSRuleList		Geerbt von `CSSGroupingRule`: die Liste der Regeln innerhalb des Ebenenblocks.
$insertRule(rule, index)	function	index = 0	Geerbt: fügt eine Regel als Text an Position `index` in den Block ein und gibt den Index zurück.
$deleteRule(index)	function		Geerbt: entfernt die Regel an Position `index` aus dem Block.

Beispiele

Ebenen in einem Stylesheet auflisten

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @layer base { body { margin: 0; } }
  @layer { p { color: red; } }
`);

for (const rule of sheet.cssRules) {
  if (rule instanceof CSSLayerBlockRule) {
    console.log(rule.name || '(anonym)', rule.cssRules.length);
  }
}

base 1 (anonym) 1

Regel zur Laufzeit in eine bestimmte Ebene einfügen

const sheet = new CSSStyleSheet();
sheet.replaceSync('@layer components { .btn { padding: 0.5rem; } }');
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const layer = [...sheet.cssRules]
  .find((r) => r instanceof CSSLayerBlockRule && r.name === 'components');

layer.insertRule('.btn:hover { opacity: 0.8; }', layer.cssRules.length);
console.log(layer.cssRules.length);
console.log(layer.cssRules[1].cssText);

2 .btn:hover { opacity: 0.8; }

Verschachtelte Ebenen rekursiv mit vollem Pfad ausgeben

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @layer framework {
    @layer reset { * { box-sizing: border-box; } }
    @layer theme { :root { --accent: teal; } }
  }
`);

const walk = (rules, prefix = '') => {
  for (const rule of rules) {
    if (rule instanceof CSSLayerBlockRule) {
      const full = prefix ? `${prefix}.${rule.name}` : rule.name;
      console.log(full);
      walk(rule.cssRules, full);
    }
  }
};

walk(sheet.cssRules);

framework framework.reset framework.theme

// Wichtig · Fallstricke

Nur der lokale Name: name enthält bei verschachtelten Blöcken nur den Namen, der dort steht (z. B. \"reset\"), nicht den vollständigen Pfad \"framework.reset\". Den Pfad muss man selbst über parentRule oder rekursiv zusammensetzen.
Anonyme Ebenen: name === \"\". Jeder anonyme Block ist eine eigene Ebene, auch wenn mehrere anonyme Blöcke gleich aussehen.
Anweisung und Block sind verschiedene Typen: @layer a, b; ergibt eine CSSLayerStatementRule. Wer nur nach CSSLayerBlockRule filtert, übersieht solche reinen Reihenfolge-Angaben.
Fremde Stylesheets: Wird auf cssRules eines Stylesheets von einer anderen Herkunft ohne passende CORS-Header zugegriffen, wirft der Browser einen SecurityError. Solche Zugriffe sollte man in try/catch einschließen.
Kompatibilität: Seit 2022 in allen aktuellen Browsern verfügbar (Chrome/Edge 99, Firefox 97, Safari 15.4). Ältere Browser ignorieren @layer-Blöcke vollständig, auch die Regeln darin. Bei Bedarf mit typeof CSSLayerBlockRule !== 'undefined' prüfen.
Ungestufte Regeln (außerhalb jeder Ebene) haben Vorrang vor allen Ebenen. Bei !important kehrt sich die Reihenfolge der Ebenen um.

Siehe auch

CSSNamespaceRule CSSKeyframeRule CSSKeyframesRule CSSPageRule CSSStyleRule