CSSLayerBlockRule.name — Eigenschaft · JavaScript-Referenz

Signatur

get CSSLayerBlockRule.name

Beschreibung

Die schreibgeschützte Eigenschaft name der Schnittstelle CSSLayerBlockRule enthält den Namen der Kaskadenschicht (Cascade Layer), den eine @layer name { … }-Blockregel festlegt. Für @layer base { … } ist der Wert also "base".

Das ist nützlich, wenn du Stylesheets zur Laufzeit untersuchen willst, etwa in Entwicklerwerkzeugen, Style-Linting-Skripten oder beim Debuggen der Reihenfolge von Schichten. So findest du heraus, welche Regeln zu welcher Schicht gehören, oder baust eine Übersicht aller Schichten eines Dokuments auf.

Wichtig: name gibt nur den Namen zurück, der in der Regel selbst steht, also nicht den vollständigen Pfad. Bei verschachtelten Blöcken wie @layer framework { @layer reset { … } } liefert die innere Regel "reset" und nicht "framework.reset". Steht in der Regel dagegen schon ein Name mit Punkt (@layer framework.reset { … }), bekommst du genau diesen Wert "framework.reset". Bei anonymen Schichten (@layer { … }) ist der Wert ein leerer String.

Rückgabewert

Typ

string

Beschreibung

Der Name der Kaskadenschicht, so wie er in der Regel steht. Bei einer anonymen Schicht ist das ein leerer String "".

Beispiele

Namen benannter und anonymer Schichten auslesen

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

for (const rule of sheet.cssRules) {
  if (rule instanceof CSSLayerBlockRule) {
    console.log(JSON.stringify(rule.name));
  }
}

"base" "" "theme.dark"

Vollständige Schichtpfade verschachtelter Blöcke ermitteln

// Hilfsfunktion: sammelt alle Schichten samt vollständigem Pfad
const collectLayers = (rules, parent = '') => {
  const result = [];
  for (const rule of rules) {
    if (rule instanceof CSSLayerBlockRule) {
      const local = rule.name || '<anonym>';
      const fullName = parent ? `${parent}.${local}` : local;
      result.push(fullName);
      result.push(...collectLayers(rule.cssRules, fullName));
    }
  }
  return result;
};

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @layer framework {
    @layer reset { * { box-sizing: border-box; } }
    @layer components { .btn { padding: 0.5rem; } }
  }
`);

console.log(collectLayers(sheet.cssRules));

["framework", "framework.reset", "framework.components"]

Alle Schichten der Seite auflisten (mit Schutz vor CORS-Fehlern)

const layerNames = new Set();

for (const sheet of document.styleSheets) {
  let rules;
  try {
    rules = sheet.cssRules; // wirft bei fremden Stylesheets ohne CORS
  } catch {
    continue;
  }
  for (const rule of rules) {
    if (rule instanceof CSSLayerBlockRule && rule.name) {
      layerNames.add(rule.name);
    }
  }
}

console.log([...layerNames]);

z. B. ["reset", "base", "components"]

Die Eigenschaft ist schreibgeschützt

'use strict';
const sheet = new CSSStyleSheet();
sheet.replaceSync('@layer base { a { color: blue; } }');
const rule = sheet.cssRules[0];

try {
  rule.name = 'neu';
} catch (err) {
  console.log(err.name);
}
console.log(rule.name);

TypeError base

// Wichtig · Fallstricke

Nur der eigene Name: Bei verschachtelten @layer-Blöcken enthält name nicht den Pfad der übergeordneten Schichten. Den vollständigen Namen musst du selbst zusammensetzen (siehe Beispiel 2).
Anonyme Schichten: Hier ist der Wert "". Mehrere anonyme Schichten sind jeweils eigene Schichten, lassen sich über name aber nicht unterscheiden.
Schreibgeschützt: Eine Zuweisung wird im nicht-strikten Modus stillschweigend ignoriert und löst im Strict Mode (also auch in ES-Modulen) einen TypeError aus. Um eine Schicht umzubenennen, musst du die Regel löschen und neu einfügen (deleteRule() und insertRule()).
Nicht verwechseln: Die Anweisungsform @layer a, b; ergibt eine CSSLayerStatementRule. Die hat keine name-Eigenschaft, sondern das Array nameList.
CORS: Wenn du cssRules von Stylesheets anderer Herkunft ohne passende CORS-Header liest, wird ein SecurityError geworfen. Fang diesen Fehler ab.
Kompatibilität: Wird seit 2022 von allen aktuellen Browsern unterstützt (Chrome/Edge 99, Firefox 97, Safari 15.4). Ältere Browser kennen CSSLayerBlockRule nicht. Prüf das vorher mit typeof CSSLayerBlockRule !== 'undefined'.

Siehe auch

CSSLayerBlockRule CSSLayerStatementRule CSSLayerStatementRule.nameList CSSGroupingRule.cssRules CSSStyleSheet.prototype.replaceSync() Document.styleSheets CSSKeyframesRule.name