CSSStartingStyleRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSStartingStyleRule extends CSSGroupingRule

Beschreibung

Das Interface CSSStartingStyleRule steht im CSS Object Model (CSSOM) für eine @starting-style-At-Regel. Mit @starting-style legt man Stilwerte fest, die ein Element vor seinem ersten Stil-Update hat, also zum Beispiel direkt nach dem Einfügen ins DOM oder wenn es von display: none auf sichtbar wechselt. So lassen sich Einblend-Übergänge umsetzen, etwa für Popover, Dialoge oder Toast-Meldungen, ohne dafür JavaScript-Tricks wie requestAnimationFrame oder das Erzwingen eines Reflows zu brauchen.

Das Interface erbt von CSSGroupingRule und bringt keine eigenen Eigenschaften oder Methoden mit. Alles Nötige kommt aus der Vererbung:

cssRules: eine CSSRuleList mit den Regeln innerhalb des Blocks
insertRule(rule, index) und deleteRule(index): Regeln im Block hinzufügen oder entfernen
cssText, parentRule und parentStyleSheet aus CSSRule

Objekte dieses Typs erzeugt man nicht selbst. Man bekommt sie beim Durchlaufen von CSSStyleSheet.cssRules oder den cssRules einer verschachtelten Stilregel. Sinnvoll ist das Interface vor allem für Werkzeuge wie Style-Inspektoren, CSS-in-JS-Bibliotheken und Theme-Editoren sowie für Code, der Startwerte von Animationen zur Laufzeit anpassen will.

Beispiele

@starting-style-Regel in einem erzeugten Stylesheet auslesen

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  .popup { opacity: 1; transition: opacity 0.3s; }
  @starting-style {
    .popup { opacity: 0; }
  }
`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const rule = sheet.cssRules[1];
console.log(rule instanceof CSSStartingStyleRule);
console.log(rule.cssRules.length);
console.log(rule.cssRules[0].selectorText);
console.log(rule.cssRules[0].style.opacity);

true 1 .popup 0

Alle @starting-style-Regeln der Seite finden

const findStartingStyleRules = () => {
  const result = [];
  const walk = (rules) => {
    for (const rule of rules) {
      if (rule instanceof CSSStartingStyleRule) result.push(rule);
      // Auch verschachtelte Blöcke (@media, @supports, CSS-Nesting) durchsuchen
      if (rule.cssRules) walk(rule.cssRules);
    }
  };
  for (const sheet of document.styleSheets) {
    try {
      walk(sheet.cssRules);
    } catch (err) {
      // Stylesheets von fremden Ursprüngen ohne CORS lassen sich nicht auslesen
      console.warn('Nicht lesbar:', sheet.href);
    }
  }
  return result;
};

console.log(`${findStartingStyleRules().length} @starting-style-Regel(n) gefunden`);

2 @starting-style-Regel(n) gefunden

Startwerte zur Laufzeit ändern (Toast-Einblendung)

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  .toast { opacity: 1; transform: none; transition: opacity 0.4s, transform 0.4s; }
  @starting-style { .toast { opacity: 0; } }
`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const starting = [...sheet.cssRules].find((r) => r instanceof CSSStartingStyleRule);

// Zusätzliche Startregel: Toast gleitet von unten herein
starting.insertRule('.toast { transform: translateY(1rem); }', starting.cssRules.length);
console.log(starting.cssRules.length);

const toast = document.createElement('div');
toast.className = 'toast';
toast.textContent = 'Gespeichert!';
document.body.append(toast); // blendet sich ein und gleitet nach oben

2

Feature-Erkennung

const supportsStartingStyle = 'CSSStartingStyleRule' in window;

if (!supportsStartingStyle) {
  // Ersatzlösung: Element ohne Übergang sofort anzeigen
  document.documentElement.classList.add('no-starting-style');
}
console.log(supportsStartingStyle);

true

// Wichtig · Fallstricke

Browser-Unterstützung: Chrome/Edge ab 117, Safari ab 17.5, Firefox ab 129. Ältere Browser ignorieren den @starting-style-Block im Stylesheet einfach, das Element erscheint dann ohne Übergang. Zur Erkennung eignet sich 'CSSStartingStyleRule' in window, denn CSS.supports() kann keine At-Regeln prüfen.
Kein Konstruktor: new CSSStartingStyleRule() wirft einen TypeError. Regeln legt man über insertRule() oder replaceSync() bzw. replace() eines Stylesheets an.
Verschachtelte Form: Steht @starting-style innerhalb einer Stilregel (CSS-Nesting), taucht es in deren cssRules auf. In neueren Browsern stecken die Deklarationen dann in einem CSSNestedDeclarations-Objekt statt in einer CSSStyleRule.
Cross-Origin: Liest man cssRules von Stylesheets anderer Ursprünge ohne CORS-Freigabe, wird ein SecurityError geworfen. Den Zugriff deshalb in try/catch einschließen.
Nur wirksam mit Übergang: Startwerte haben nur dann einen sichtbaren Effekt, wenn für die jeweilige Eigenschaft eine transition gesetzt ist. Für display und overlay braucht man zusätzlich transition-behavior: allow-discrete.
Die Formatierung von cssText (Leerzeichen, Zeilenumbrüche) ist nicht festgelegt und unterscheidet sich je nach Browser.

Siehe auch

CSSCounterStyleRule CSSStyleRule CSSGroupingRule CSSNamespaceRule CSSPageRule