CSSImportRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSImportRule extends CSSRule

Beschreibung

CSSImportRule ist die CSSOM-Darstellung einer @import-At-Regel. Solche Objekte bekommst du, wenn du über CSSStyleSheet.cssRules iterierst. Zu erkennen sind sie an rule instanceof CSSImportRule oder am veralteten rule.type === CSSRule.IMPORT_RULE (Wert 3). Einen eigenen Konstruktor gibt es nicht. Neue Import-Regeln legst du mit CSSStyleSheet.insertRule() an.

Neben den geerbten Eigenschaften von CSSRule (cssText, parentStyleSheet, parentRule) bietet die Schnittstelle:

href (nur lesen): die URL genau so, wie sie in der Regel steht. Relative Pfade werden nicht aufgelöst.
media: eine MediaList mit den Medienabfragen der Regel. Eine Zuweisung an media wird an media.mediaText weitergereicht.
styleSheet (nur lesen): das importierte CSSStyleSheet. Der Wert ist null, solange das Stylesheet nicht geladen ist oder wenn der Import nicht angewendet wird.
layerName (nur lesen): der Name der Kaskadenebene aus layer(name). Bei einer anonymen Ebene (layer) ist er ein leerer String, ohne Ebene null.
supportsText (nur lesen): die Bedingung aus supports(...) oder null.

Typische Einsatzfälle: Du analysierst Stylesheets, etwa um Abhängigkeiten aufzulisten oder CSS rekursiv einzusammeln. Du schreibst Werkzeuge wie Style-Inspektoren oder Bundler-Hilfen im Browser. Oder du fügst zur Laufzeit gezielt Importe hinzu. Über styleSheet steigst du in die Regeln des importierten Stylesheets ab und kannst so ganze Import-Bäume durchlaufen.

Rückgabewert

Typ

CSSImportRule

Beschreibung

Wird nicht direkt erzeugt. Instanzen findest du in CSSStyleSheet.cssRules bzw. CSSRuleList.

Beispiele

Alle @import-Regeln eines Dokuments auflisten

// Durchsucht alle Stylesheets nach @import-Regeln
for (const sheet of document.styleSheets) {
  let rules;
  try {
    rules = sheet.cssRules;
  } catch {
    // Fremd-Origin-Stylesheet ohne CORS: kein Zugriff
    continue;
  }
  for (const rule of rules) {
    if (rule instanceof CSSImportRule) {
      console.log(rule.href, '| Medien:', rule.media.mediaText || 'alle', '| Ebene:', rule.layerName);
    }
  }
}

Import-Baum rekursiv durchlaufen

// Liefert alle Import-URLs, auch verschachtelte
const collectImports = (sheet, depth = 0, result = []) => {
  let rules;
  try {
    rules = sheet.cssRules;
  } catch {
    return result;
  }
  for (const rule of rules) {
    if (!(rule instanceof CSSImportRule)) continue;
    result.push(`${'  '.repeat(depth)}${rule.href}`);
    // styleSheet ist null, wenn noch nicht geladen
    if (rule.styleSheet) collectImports(rule.styleSheet, depth + 1, result);
  }
  return result;
};

window.addEventListener('load', () => {
  const tree = [...document.styleSheets].flatMap((s) => collectImports(s));
  console.log(tree.join('\n'));
});

base.css variables.css fonts.css components.css

@import zur Laufzeit einfügen und Medien ändern

const style = document.createElement('style');
style.textContent = 'body { margin: 0; }';
document.head.append(style);

const sheet = style.sheet;
// @import muss VOR allen normalen Regeln stehen → Index 0
sheet.insertRule('@import url("dark.css") layer(theme) screen;', 0);

const importRule = sheet.cssRules[0];
console.log(importRule.href);       // "dark.css"
console.log(importRule.layerName);  // "theme"

// Medienliste ändern (wird an media.mediaText weitergereicht)
importRule.media = 'screen and (prefers-color-scheme: dark)';
console.log(importRule.cssText);

dark.css theme @import url("dark.css") layer(theme) screen and (prefers-color-scheme: dark);

// Wichtig · Fallstricke

Reihenfolge: @import darf nur vor allen anderen Regeln stehen. Davor erlaubt sind nur @charset und @layer-Anweisungen. Fügst du eine Import-Regel mit insertRule() an einer späteren Stelle ein, wird ein HierarchyRequestError ausgelöst.
Konstruierte Stylesheets: In new CSSStyleSheet() sind @import-Regeln nicht erlaubt. replace()/replaceSync() ignorieren sie und geben eine Konsolenwarnung aus. insertRule() wirft einen SyntaxError.
Cross-Origin: Wird das importierte Stylesheet von einer fremden Domain ohne passende CORS-Header geladen, wirft der Zugriff auf rule.styleSheet.cssRules einen SecurityError. Umschließe ihn deshalb mit try/catch.
styleSheet kann null sein: Das gilt, solange das Laden noch läuft, und auch dann, wenn eine supports()-Bedingung nicht erfüllt ist. Werte die Regeln am besten erst nach dem load-Ereignis aus.
href ist nicht aufgelöst: Brauchst du die absolute URL, rechne sie selbst aus, z. B. mit new URL(rule.href, rule.parentStyleSheet.href ?? document.baseURI).
Kompatibilität: href, media und styleSheet werden überall unterstützt. layerName gibt es in allen aktuellen Browsern etwa seit 2022/2023. supportsText wird bisher nur eingeschränkt unterstützt (u. a. in Firefox); prüfe es mit 'supportsText' in CSSImportRule.prototype.
Performance: Verschachtelte @imports laden nacheinander und verzögern das Rendern. In Produktionsumgebungen sind gebündelte Stylesheets oder mehrere <link>-Elemente meist schneller.

Siehe auch

CSSSupportsRule CSSMediaRule CSSPageRule CSSPropertyRule CSSScopeRule