CSSPropertyRule.initialValue — Eigenschaft · JavaScript-Referenz

Signatur

CSSPropertyRule.initialValue

Beschreibung

Die Eigenschaft initialValue einer CSSPropertyRule gibt den Wert zurück, der in der Regel @property im Deskriptor initial-value steht. Dieser Wert gilt für die benutzerdefinierte Eigenschaft (z. B. --brand-color), solange ihr kein anderer Wert zugewiesen oder vererbt wurde.

Wurde kein initial-value angegeben, ist der Rückgabewert null. Das ist nur mit syntax: "*" erlaubt (universelle Syntax). Bei jeder anderen Syntax, etwa "<color>" oder "<length>", ist initial-value Pflicht. Fehlt er dort, ist die ganze @property-Regel ungültig und taucht im CSSOM überhaupt nicht auf.

In der Praxis nutzt man initialValue, um registrierte Eigenschaften zu prüfen. Typische Fälle sind Design-Token-Werkzeuge, Debugging-Hilfen und Tests: Man liest aus, welche Standardwerte ein Stylesheet festlegt, ohne das CSS selbst zu zerlegen. Den Wert direkt ändern kann man nicht. Dafür muss man die Regel über CSSStyleSheet.insertRule() bzw. deleteRule() ersetzen oder CSS.registerProperty() verwenden.

Rückgabewert

Typ

string | null

Beschreibung

Der Anfangswert als serialisierter CSS-String (z. B. "rgb(255, 0, 0)" oder "0px"). null, wenn in der Regel kein initial-value angegeben wurde.

Beispiele

Anfangswert einer @property-Regel auslesen

// CSS: @property --brand-color { syntax: "<color>"; inherits: false; initial-value: rebeccapurple; }
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @property --brand-color {
    syntax: "<color>";
    inherits: false;
    initial-value: rebeccapurple;
  }
`);

const rule = sheet.cssRules[0];
if (rule instanceof CSSPropertyRule) {
  console.log(rule.name);         // Name der Eigenschaft
  console.log(rule.initialValue); // Anfangswert
}

--brand-color rebeccapurple

null bei universeller Syntax ohne initial-value

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @property --anything {
    syntax: "*";
    inherits: true;
  }
`);

const rule = sheet.cssRules[0];
console.log(rule.initialValue);
console.log(rule.initialValue ?? "(kein Anfangswert)");

null (kein Anfangswert)

Alle registrierten Eigenschaften des Dokuments auflisten

const collectPropertyRules = () => {
  const result = [];
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // kann bei fremden Stylesheets (CORS) werfen
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (rule instanceof CSSPropertyRule) {
        result.push({
          name: rule.name,
          syntax: rule.syntax,
          inherits: rule.inherits,
          initialValue: rule.initialValue
        });
      }
    }
  }
  return result;
};

console.table(collectPropertyRules());

Tabelle mit name, syntax, inherits und initialValue aller @property-Regeln

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie rule.initialValue = "red" wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus.
Ungültige Regeln fehlen ganz: Hat eine Regel keine Syntax "*" und keinen gültigen initial-value, verwirft der Browser sie. Sie erscheint dann nicht in cssRules, und null kann nicht auftreten. Auch ein berechnungsabhängiger Anfangswert wie 3em für <length> ist ungültig. Der Wert muss unabhängig vom Element berechenbar sein.
Serialisierung: Der zurückgegebene String kann je nach Browser normalisiert sein. Zum Vergleichen besser nicht auf exakte Schreibweise prüfen.
Nur @property, nicht CSS.registerProperty(): Eigenschaften, die per JavaScript mit CSS.registerProperty() registriert wurden, erzeugen keine CSSPropertyRule und lassen sich darüber nicht auslesen.
CORS: Der Zugriff auf cssRules fremder Stylesheets ohne passende CORS-Header wirft einen SecurityError.
Kompatibilität: Firefox unterstützt @property erst ab Version 128. Bei Bedarf vorher mit typeof CSSPropertyRule !== "undefined" prüfen.

Siehe auch

CSSPropertyRule.inherits CSSPropertyRule.name CSSPropertyRule.syntax CSSImportRule.layerName CSSImportRule.media