CSSPropertyRule.inherits — Eigenschaft · JavaScript-Referenz

Signatur

CSSPropertyRule.inherits

Beschreibung

Die Eigenschaft inherits der Schnittstelle CSSPropertyRule liefert den Wert des Deskriptors inherits einer @property-Regel. Mit ihr lässt sich per JavaScript prüfen, ob eine registrierte benutzerdefinierte Eigenschaft (z. B. --main-color) ihren Wert vom Elternelement übernimmt (true) oder ob jedes Element ohne eigene Zuweisung auf den initial-value zurückfällt (false).

Nützlich ist das vor allem in Werkzeugen, die Stylesheets untersuchen: Design-Token-Inspektoren, Debugging-Hilfen, Test-Suites, die sicherstellen, dass Custom Properties korrekt registriert sind, oder Bibliotheken, die herausfinden wollen, wie sich eine Variable im Kaskaden-Baum verhält.

An das Objekt kommt man, indem man über document.styleSheets und deren cssRules läuft und nach Instanzen von CSSPropertyRule filtert. Die Eigenschaft ist schreibgeschützt. Wer das Verhalten ändern will, muss die Regel entfernen und neu anlegen. Einmal registrierte Eigenschaften lassen sich allerdings oft nicht sauber überschreiben (siehe Hinweise).

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Regel inherits: true festlegt, sonst false.

Beispiele

Vererbungs-Flag einer @property-Regel auslesen

// CSS im Dokument:
// @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];
console.log(rule instanceof CSSPropertyRule); // true
console.log(rule.name, rule.inherits);

true --brand-color false

Alle registrierten Custom Properties eines Dokuments auflisten

const collectPropertyRules = () => {
  const result = [];
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // kann bei fremden Stylesheets werfen (CORS)
    } 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, initialValue je @property-Regel

Test: Nicht vererbende Tokens finden

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @property --gap { syntax: '<length>'; inherits: true; initial-value: 8px; }
  @property --angle { syntax: '<angle>'; inherits: false; initial-value: 0deg; }
`);

const nonInherited = [...sheet.cssRules]
  .filter((r) => r instanceof CSSPropertyRule && !r.inherits)
  .map((r) => r.name);

console.log(nonInherited);

["--angle"]

Schreibschutz der Eigenschaft

'use strict';
const sheet = new CSSStyleSheet();
sheet.replaceSync(`@property --x { syntax: '*'; inherits: true; }`);
const rule = sheet.cssRules[0];

try {
  rule.inherits = false; // Getter ohne Setter
} catch (err) {
  console.log(err.name);
}
console.log(rule.inherits);

TypeError true

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wird im nicht-strikten Modus stillschweigend ignoriert und löst im Strict Mode einen TypeError aus.
Pflicht-Deskriptor: Laut Spezifikation muss eine @property-Regel syntax und inherits enthalten. Fehlt einer davon, ist die Regel ungültig und erscheint gar nicht erst als CSSPropertyRule in cssRules. Ein ungültiger initial-value hat dieselbe Wirkung (außer bei syntax: '*').
CORS: Der Zugriff auf cssRules von Stylesheets aus fremden Quellen ohne passende CORS-Header wirft einen SecurityError. Deshalb gehört er in ein try/catch.
Die per JavaScript registrierten Eigenschaften (CSS.registerProperty()) tauchen nicht als CSSPropertyRule auf. Für sie gibt es keine vergleichbare Lese-API.
Browser-Unterstützung: Chromium ab 85, Safari ab 16.4, Firefox erst ab 128. Vorher mit typeof CSSPropertyRule !== 'undefined' prüfen.

Siehe auch

CSSPropertyRule CSSPropertyRule.name CSSPropertyRule.syntax CSSPropertyRule.initialValue CSS.registerProperty() CSSStyleSheet.cssRules ResizeObserverSize.inlineSize