CSSPropertyRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSPropertyRule extends CSSRule

Beschreibung

CSSPropertyRule gehört zur CSS Properties and Values API (Teil von CSS Houdini). Jede @property-Regel in einem Stylesheet erscheint im CSSOM als Objekt dieses Typs. Man findet es in CSSStyleSheet.cssRules oder in den cssRules verschachtelter Gruppenregeln wie @media oder @layer.

Mit @property registriert man eine benutzerdefinierte Eigenschaft (z. B. --hauptfarbe) mit einem festen Typ, einem Anfangswert und einer Angabe zur Vererbung. So kann der Browser die Eigenschaft animieren und interpolieren (etwa Farbverläufe oder Winkel) und ungültige Werte verwerfen. Mit CSSPropertyRule liest du diese Registrierung aus JavaScript aus, zum Beispiel für Entwicklerwerkzeuge, Design-Token-Übersichten oder zur Fehlersuche.

Alle Eigenschaften der Schnittstelle sind schreibgeschützt. Ändern kannst du eine Registrierung nur, indem du die Regel mit deleteRule() entfernst und mit insertRule() neu einfügst. Es gibt keinen öffentlichen Konstruktor. Instanzen entstehen nur, wenn der Browser CSS parst.

Neben den geerbten Eigenschaften von CSSRule (cssText, parentRule, parentStyleSheet) bietet die Schnittstelle name, syntax, inherits und initialValue.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Schreibgeschützte Eigenschaft: Name der benutzerdefinierten Eigenschaft einschließlich `--`, z. B. `"--winkel"`.
$syntax Pflicht	string		Schreibgeschützte Eigenschaft: die Syntaxbeschreibung aus dem Deskriptor `syntax`, z. B. `"<color>"`, `"<length> \| auto"` oder `"*"`.
$inherits Pflicht	boolean		Schreibgeschützte Eigenschaft: `true`, wenn die Eigenschaft standardmäßig vererbt wird (Deskriptor `inherits: true`).
$initialValue	string \| null	null	Schreibgeschützte Eigenschaft: der Anfangswert aus `initial-value` als String. Fehlt der Deskriptor (nur bei `syntax: "*"` erlaubt), ist der Wert `null`.

Rückgabewert

Typ

CSSPropertyRule

Beschreibung

Ein Objekt, das eine geparste @property-Regel im CSSOM darstellt. Du bekommst es beim Durchlaufen von cssRules.

Beispiele

Alle @property-Regeln eines Dokuments auflisten

// Beispiel-CSS im Dokument:
// @property --winkel { syntax: "<angle>"; inherits: false; initial-value: 0deg; }

const sammleProperties = (regeln, ergebnis = []) => {
  for (const regel of regeln) {
    if (regel instanceof CSSPropertyRule) {
      ergebnis.push({
        name: regel.name,
        syntax: regel.syntax,
        inherits: regel.inherits,
        initialValue: regel.initialValue
      });
    } else if (regel.cssRules) {
      // Verschachtelte Gruppenregeln (@media, @layer, @supports) mit durchsuchen
      sammleProperties(regel.cssRules, ergebnis);
    }
  }
  return ergebnis;
};

const alle = [...document.styleSheets].flatMap((sheet) => {
  try {
    return sammleProperties(sheet.cssRules);
  } catch {
    return []; // Stylesheets von fremden Ursprüngen ohne CORS überspringen
  }
});

console.table(alle);

┌─────────┬────────────┬───────────┬──────────┬──────────────┐ │ (index) │ name │ syntax │ inherits │ initialValue │ ├─────────┼────────────┼───────────┼──────────┼──────────────┤ │ 0 │ '--winkel' │ '<angle>' │ false │ '0deg' │ └─────────┴────────────┴───────────┴──────────┴──────────────┘

@property zur Laufzeit per insertRule anlegen und auslesen

const sheet = new CSSStyleSheet();
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const index = sheet.insertRule(`
  @property --hauptfarbe {
    syntax: "<color>";
    inherits: true;
    initial-value: rebeccapurple;
  }
`);

const regel = sheet.cssRules[index];
console.log(regel instanceof CSSPropertyRule);
console.log(regel.name, regel.syntax, regel.inherits, regel.initialValue);

true --hauptfarbe <color> true rebeccapurple

Registrierung ändern: Regel ersetzen statt überschreiben

const ersetzeInitialwert = (sheet, propName, neuerWert) => {
  const regeln = [...sheet.cssRules];
  const index = regeln.findIndex(
    (r) => r instanceof CSSPropertyRule && r.name === propName
  );
  if (index === -1) return false;

  const alt = regeln[index];
  // Eigenschaften sind schreibgeschützt, deshalb löschen und neu einfügen
  sheet.deleteRule(index);
  sheet.insertRule(
    `@property ${alt.name} {
      syntax: "${alt.syntax}";
      inherits: ${alt.inherits};
      initial-value: ${neuerWert};
    }`,
    index
  );
  return true;
};

const sheet = new CSSStyleSheet();
sheet.replaceSync('@property --abstand { syntax: "<length>"; inherits: false; initial-value: 8px; }');
ersetzeInitialwert(sheet, '--abstand', '16px');
console.log(sheet.cssRules[0].initialValue);

16px

Feature-Erkennung

const unterstuetzt = typeof CSSPropertyRule !== 'undefined';
console.log(unterstuetzt ? '@property wird im CSSOM unterstützt' : 'Kein CSSPropertyRule – Fallback nötig');

@property wird im CSSOM unterstützt

Siehe auch

CSSImportRule CSSScopeRule CSSSupportsRule CSSGroupingRule CSSPageRule