CSSScopeRule.start — Eigenschaft · JavaScript-Referenz

Signatur

CSSScopeRule.start

Beschreibung

Die schreibgeschützte Eigenschaft start der Schnittstelle CSSScopeRule gibt den ersten Teil der Einleitung (Prelude) einer @scope-Regel zurück: die Selektorliste in der ersten Klammer, die die Scope-Root festlegt. Bei @scope (.card) to (.card-content) { … } liefert start also den String ".card".

Der Wert wird serialisiert zurückgegeben, also so, wie der Browser den Selektor normalisiert hat. Überflüssige Leerzeichen fallen weg, und bei Selektorlisten steht nach jedem Komma genau ein Leerzeichen. Den Wert sollte man deshalb nicht Zeichen für Zeichen mit dem Quelltext vergleichen.

Fehlt die Scope-Root, etwa bei @scope { … } innerhalb eines <style>-Elements, gibt start null zurück. Die Scope-Root ist dann implizit das Elternelement des <style>-Elements.

Nützlich ist die Eigenschaft vor allem für Werkzeuge, die Stylesheets untersuchen: Debugging-Tools, CSS-Linter, Style-Inspektoren oder Skripte, die herausfinden wollen, welche Komponenten eigene Scope-Regeln haben.

Rückgabewert

Typ

string | null

Beschreibung

Die serialisierte Selektorliste der Scope-Root, z. B. ".card", oder null, wenn die @scope-Regel keine Scope-Root angibt.

Beispiele

Scope-Root aus einem erzeugten Stylesheet auslesen

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @scope (.card) to (.card-content) {
    img { border: 2px solid black; }
  }
`);

const rule = sheet.cssRules[0];

if (rule instanceof CSSScopeRule) {
  console.log(rule.start);
  console.log(rule.end);
}

.card .card-content

Alle @scope-Regeln der Seite auflisten

const findScopeRules = (rules, found = []) => {
  for (const rule of rules) {
    if (rule instanceof CSSScopeRule) {
      found.push({ start: rule.start, end: rule.end });
    }
    // Verschachtelte Regeln (z. B. in @media) ebenfalls durchsuchen
    if (rule.cssRules) findScopeRules(rule.cssRules, found);
  }
  return found;
};

const result = [];
for (const sheet of document.styleSheets) {
  try {
    findScopeRules(sheet.cssRules, result);
  } catch {
    // Stylesheets fremder Herkunft ohne CORS-Freigabe sind nicht lesbar
  }
}
console.table(result);

Tabelle mit den Spalten start und end, z. B. ".card" | ".card-content"

Fehlende Scope-Root ergibt null

const style = document.createElement('style');
style.textContent = '@scope { p { color: teal; } }';
document.querySelector('#widget').append(style);

const rule = style.sheet.cssRules[0];
console.log(rule.start); // Scope-Root ist implizit #widget
console.log(rule.start ?? 'implizite Scope-Root (Elternelement)');

null implizite Scope-Root (Elternelement)

Normalisierung des Selektors

const sheet = new CSSStyleSheet();
sheet.replaceSync('@scope (  .a,.b   >  .c ) { p { margin: 0; } }');
console.log(JSON.stringify(sheet.cssRules[0].start));

".a, .b > .c"

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung an start hat keine Wirkung und wirft im Strict Mode einen TypeError. Wer die Scope-Root ändern will, muss die Regel entfernen (deleteRule()) und neu einfügen (insertRule()).
Auf null prüfen: Fehlt die Scope-Root, ist der Wert null und kein leerer String. Vor String-Methoden wie includes() also z. B. mit ?. oder ?? absichern.
Serialisierter Wert: Die Schreibweise kann vom Quelltext abweichen (Leerzeichen, Kombinatoren). Für Vergleiche besser den Selektor normalisieren oder element.matches(rule.start) verwenden.
Browser-Unterstützung: @scope und CSSScopeRule gibt es in Chromium ab Version 118 und in Safari ab 17.4. Firefox unterstützt beides erst in neueren Versionen. Vorher auf Unterstützung prüfen, z. B. mit typeof CSSScopeRule !== 'undefined'. Nicht unterstützende Browser verwerfen die ganze @scope-Regel; sie taucht dann gar nicht in cssRules auf.
Stylesheets anderer Herkunft: Beim Zugriff auf cssRules eines fremden Stylesheets ohne CORS-Freigabe wird ein SecurityError ausgelöst.

Siehe auch

CSSScopeRule CSSScopeRule.end CSSGroupingRule CSSStyleSheet.cssRules CSSStyleSheet.prototype.insertRule() Element.prototype.matches() CSSNamespaceRule.prefix