CSSPropertyRule.syntax — Eigenschaft · JavaScript-Referenz

Signatur

CSSPropertyRule.syntax

Beschreibung

Die Eigenschaft syntax einer CSSPropertyRule enthält den Wert des Deskriptors syntax aus einer @property-Regel, und zwar ohne die umschließenden Anführungszeichen. Beispiele sind "<color>", "<length> | <percentage>", "<number>+" oder das Universal-Syntax-Zeichen "*". Diese Syntax legt fest, welche Werte die benutzerdefinierte Eigenschaft annehmen darf und wie der Browser sie berechnet und interpoliert.

Gebraucht wird die Eigenschaft vor allem in Werkzeugen, Design-System-Bibliotheken und Debugging-Code. Damit lässt sich zur Laufzeit prüfen, welche benutzerdefinierten Eigenschaften mit welchem Typ registriert sind. Das ist zum Beispiel wichtig, wenn man wissen will, ob sich eine Variable wie --angle animieren lässt. Das geht nur, wenn sie einen konkreten Typ wie <angle> hat und nicht *.

An die Regel kommt man über document.styleSheets und CSSStyleSheet.cssRules: Man filtert nach Instanzen von CSSPropertyRule. Eigenschaften, die per JavaScript mit CSS.registerProperty() registriert wurden, tauchen nicht als CSSPropertyRule auf, weil sie in keinem Stylesheet stehen.

Rückgabewert

Typ

string

Beschreibung

Die Syntax der registrierten Eigenschaft als String ohne Anführungszeichen, z. B. <color> oder *.

Beispiele

Syntax einer @property-Regel auslesen

// CSS im Stylesheet:
// @property --brand-color {
//   syntax: "<color>";
//   inherits: false;
//   initial-value: rebeccapurple;
// }

const sheet = document.styleSheets[0];
const rule = [...sheet.cssRules].find(
  (r) => r instanceof CSSPropertyRule && r.name === '--brand-color'
);

console.log(rule.syntax);

<color>

Alle registrierten Eigenschaften mit Typ 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 je @property-Regel

Prüfen, ob eine Variable animierbar typisiert ist

const isTyped = (propName) => {
  for (const sheet of document.styleSheets) {
    for (const rule of sheet.cssRules) {
      if (rule instanceof CSSPropertyRule && rule.name === propName) {
        // '*' bedeutet: beliebiger Wert, keine Interpolation möglich
        return rule.syntax !== '*';
      }
    }
  }
  return false; // nicht per @property registriert
};

console.log(isTyped('--angle'));

true

Schreibversuch ohne Wirkung

const rule = [...document.styleSheets[0].cssRules]
  .find((r) => r instanceof CSSPropertyRule);

rule.syntax = '<length>'; // wird ignoriert (im Strict Mode kein Fehler bei Accessor ohne Setter? -> TypeError)
console.log(rule.syntax);

<color>

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung ändert nichts. Weil die Eigenschaft nur einen Getter hat, wirft die Zuweisung im Strict Mode (z. B. in ES-Modulen) einen TypeError. Um die Syntax zu ändern, muss man die Regel entfernen und neu einfügen (deleteRule()/insertRule()).
Eine @property-Regel ohne gültigen syntax-Deskriptor ist ungültig und erscheint gar nicht erst in cssRules.
Per CSS.registerProperty() registrierte Eigenschaften lassen sich über diese Schnittstelle nicht auslesen.
Auf cssRules von Stylesheets anderer Herkunft ohne CORS-Freigabe zuzugreifen, löst einen SecurityError aus. Deshalb in try/catch kapseln.
Browser-Kompatibilität: Chromium seit Version 85, Safari seit 16.4, Firefox erst seit 128. Für ältere Browser vorher mit typeof CSSPropertyRule !== 'undefined' prüfen.
Wie Leerraum im zurückgegebenen String aussieht (z. B. bei <length> | <percentage>), kann je nach Browser leicht unterschiedlich normalisiert sein. Strings deshalb nicht streng vergleichen.

Siehe auch

CSSPositionTryRule.style CSSPropertyRule.name CSSPropertyRule.inherits CSSPropertyRule.initialValue CSSScopeRule.start