CSSImportRule.layerName — Eigenschaft · JavaScript-Referenz

Signatur

get CSSImportRule.prototype.layerName

Beschreibung

Die schreibgeschützte Eigenschaft layerName einer CSSImportRule zeigt, ob und in welche Kaskadenschicht (Cascade Layer) ein Stylesheet über @import geladen wird. In CSS schreibt man das z. B. als @import url("reset.css") layer(reset);. Die Regeln des importierten Stylesheets landen dann in der Schicht reset und haben in der Kaskade die Priorität dieser Schicht.

Je nach Schreibweise gibt es drei mögliche Rückgabewerte:

@import url(x.css) layer(name); ergibt "name". Bei verschachtelten Schichten wie layer(framework.base) kommt der vollständige Punktname "framework.base" zurück.
@import url(x.css) layer; (anonyme Schicht) ergibt den leeren String "".
@import url(x.css); ohne das Schlüsselwort layer ergibt null.

Die Eigenschaft hilft vor allem bei Werkzeugen, die Stylesheets untersuchen: Debugging-Overlays, Linter im Browser, Tests für Design-Systeme oder Skripte, die prüfen, ob alle Drittanbieter-Styles richtig in Schichten eingeordnet sind.

Rückgabewert

Typ

string | null

Beschreibung

Der Name der Kaskadenschicht als String. Bei einer anonymen Schicht ist es der leere String "", ohne layer-Angabe null.

Beispiele

Schichtnamen von @import-Regeln auslesen

// Stylesheet mit drei @import-Varianten dynamisch anlegen
const style = document.createElement('style');
style.textContent = `
  @import url("reset.css") layer(reset);
  @import url("theme.css") layer;
  @import url("legacy.css");
`;
document.head.append(style);

for (const rule of style.sheet.cssRules) {
  if (rule instanceof CSSImportRule) {
    console.log(rule.href, '→', JSON.stringify(rule.layerName));
  }
}

reset.css → "reset" theme.css → "" legacy.css → null

null, anonyme Schicht und benannte Schicht unterscheiden

const describeLayer = (importRule) => {
  const { layerName } = importRule;
  if (layerName === null) return 'keine Schicht (normale Kaskade)';
  if (layerName === '') return 'anonyme Schicht';
  return `Schicht "${layerName}"`;
};

const style = document.createElement('style');
style.textContent = '@import url("ui.css") layer(framework.components);';
document.head.append(style);

console.log(describeLayer(style.sheet.cssRules[0]));

Schicht "framework.components"

Prüfen, ob Importe ohne Schicht vorkommen (Audit)

// Findet alle @import-Regeln ohne layer-Angabe in den Stylesheets der Seite
const findUnlayeredImports = () => {
  const result = [];
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // bei fremden Ursprüngen: SecurityError
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (rule instanceof CSSImportRule && rule.layerName === null) {
        result.push(rule.href);
      }
    }
  }
  return result;
};

console.log('Importe ohne Schicht:', findUnlayeredImports());

Importe ohne Schicht: ["legacy.css"]

// Wichtig · Fallstricke

Nur lesbar: Die Eigenschaft hat nur einen Getter. Eine Zuweisung wird im nicht-strikten Modus ignoriert. Im Strict Mode, also auch in ES-Modulen, wirft sie einen TypeError. Um die Schicht zu ändern, musst du die Regel mit deleteRule() entfernen und mit insertRule() neu einfügen.
Auf den Unterschied achten: "" und null sind beide „falsy“. Eine Prüfung wie if (!rule.layerName) hält deshalb anonyme Schichten und fehlende Schichten nicht auseinander. Nutze stattdessen === null bzw. === ''.
Konstruierte Stylesheets: In new CSSStyleSheet() mit replace()/replaceSync() sind @import-Regeln nicht erlaubt. Dort gibt es also keine CSSImportRule.
Fremde Ursprünge: Auf cssRules von Stylesheets anderer Herkunft ohne passende CORS-Freigabe darf man nicht zugreifen, das wirft einen SecurityError.
Kompatibilität: Seit 2022 in allen aktuellen Browsern verfügbar. Ältere Browser kennen die Eigenschaft nicht (sie liefert dann undefined). Prüfen lässt sich das mit 'layerName' in CSSImportRule.prototype.

Siehe auch

CSSImportRule CSSImportRule.href CSSImportRule.styleSheet CSSImportRule.supportsText CSSLayerBlockRule CSSLayerStatementRule CSSStyleSheet.cssRules