CSSPropertyRule.name — Eigenschaft · JavaScript-Referenz

Signatur

CSSPropertyRule.name

Beschreibung

Die schreibgeschützte Eigenschaft name der Schnittstelle CSSPropertyRule gibt den Namen der benutzerdefinierten Eigenschaft zurück, die über eine @property-At-Regel registriert wurde. Der Wert ist die Serialisierung des Namens aus dem Regelkopf (Prelude), also etwa "--rotation" bei @property --rotation { … }. Die beiden führenden Bindestriche gehören immer dazu.

Die Eigenschaft braucht man vor allem, wenn man Stylesheets zur Laufzeit untersucht: So lässt sich z. B. feststellen, welche typisierten Custom Properties ein Design-System registriert, oder man baut Werkzeuge, die zu jeder Eigenschaft Syntax (syntax), Vererbung (inherits) und Anfangswert (initialValue) anzeigen.

An ein CSSPropertyRule-Objekt kommt man über document.styleSheets und CSSStyleSheet.cssRules, indem man die Regeln mit instanceof CSSPropertyRule filtert. Eigenschaften, die per JavaScript mit CSS.registerProperty() registriert wurden, tauchen dort nicht auf, weil sie zu keinem Stylesheet gehören.

Rückgabewert

Typ

string

Beschreibung

Der serialisierte Name der benutzerdefinierten Eigenschaft einschließlich des Präfixes --, z. B. "--akzentfarbe".

Beispiele

Namen einer @property-Regel auslesen

// CSS im Dokument:
// @property --akzentfarbe {
//   syntax: '<color>';
//   inherits: false;
//   initial-value: rebeccapurple;
// }

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

console.log(rule?.name);

--akzentfarbe

Alle registrierten Custom Properties auflisten

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

console.table(collectPropertyRules());

┌─────────┬────────────────┬───────────┬──────────┬─────────────────┐ │ (index) │ name │ syntax │ inherits │ initial │ ├─────────┼────────────────┼───────────┼──────────┼─────────────────┤ │ 0 │ '--akzentfarbe'│ '<color>' │ false │ 'rebeccapurple' │ └─────────┴────────────────┴───────────┴──────────┴─────────────────┘

Dynamisch eingefügte Regel prüfen und Wert setzen

const sheet = new CSSStyleSheet();
sheet.insertRule(`@property --rotation {
  syntax: '<angle>';
  inherits: false;
  initial-value: 0deg;
}`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const [rule] = sheet.cssRules;
if (rule instanceof CSSPropertyRule) {
  // Name direkt für setProperty verwenden
  document.body.style.setProperty(rule.name, '45deg');
  console.log(rule.name, getComputedStyle(document.body).getPropertyValue(rule.name));
}

--rotation 45deg

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie rule.name = '--neu' wird ignoriert (im Strict Mode gibt es einen TypeError). Um den Namen zu ändern, muss man die Regel mit deleteRule() entfernen und mit insertRule() neu anlegen.
Nur Stylesheet-Regeln: Mit CSS.registerProperty() registrierte Eigenschaften erzeugen kein CSSPropertyRule-Objekt und lassen sich so nicht finden.
Ungültige Regeln fehlen: Fehlt in einer @property-Regel ein Pflichtdeskriptor (syntax, inherits bzw. initial-value bei einer anderen Syntax als *), verwirft der Browser sie. Sie taucht dann nicht in cssRules auf.
CORS: Wer cssRules eines Stylesheets von fremder Herkunft liest, bekommt ohne passende CORS-Header einen SecurityError. Deshalb gehört der Zugriff in try…catch.
Kompatibilität: Firefox unterstützt die Eigenschaft erst ab Version 128. Zur Absicherung eignet sich typeof CSSPropertyRule !== 'undefined'.

Siehe auch

CSSKeyframesRule.name CSSPropertyRule.syntax CSSPropertyRule.inherits CSSPropertyRule.initialValue CSSCounterStyleRule.name