CSSFunctionDeclarations — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSFunctionDeclarations extends CSSRule

Beschreibung

CSSFunctionDeclarations gehört zum CSS Object Model (CSSOM) und zur Spezifikation CSS Mixins and Functions. Mit einer @function-Regel definiert man eigene CSS-Funktionen wie --abstand(--faktor). Im Körper einer solchen Funktion stehen Deklarationen, also lokale Custom Properties und der Deskriptor result. Sie können mit bedingten Gruppenregeln wie @media, @supports oder @container abwechseln. Jede zusammenhängende Folge solcher Deklarationen wird im CSSOM als eigenes CSSFunctionDeclarations-Objekt dargestellt.

Diese Objekte findest du in der Eigenschaft cssRules einer CSSFunctionRule. Sie stehen auch in den cssRules einer darin verschachtelten Gruppenregel, zum Beispiel einer CSSMediaRule. Das Interface erbt von CSSRule und bietet deshalb cssText, parentRule und parentStyleSheet.

Das Interface hat genau eine eigene Eigenschaft:

style (schreibgeschützt): ein CSSFunctionDescriptors-Objekt. Es leitet sich von CSSStyleDeclaration ab. Damit liest und änderst du die Deklarationen des Blocks, etwa über style.result, getPropertyValue() oder setProperty().

Du brauchst das Interface vor allem für Werkzeuge wie DevTools, CSS-Linter, Stylesheet-Analysen oder Theme-Editoren. Damit kannst du den Inhalt benutzerdefinierter CSS-Funktionen zur Laufzeit untersuchen oder ändern. Einen Konstruktor gibt es nicht. Die Objekte entstehen nur, wenn der Browser ein Stylesheet parst.

Beispiele

Deklarationen einer @function auslesen

// Funktioniert nur in Browsern mit @function-Unterstützung
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @function --abstand(--faktor) {
    --basis: 8px;
    result: calc(var(--basis) * var(--faktor));
  }
`);

const fnRule = sheet.cssRules[0];
console.log(fnRule instanceof CSSFunctionRule, fnRule.name);

const block = fnRule.cssRules[0];
console.log(block instanceof CSSFunctionDeclarations);
console.log(block.style.getPropertyValue('--basis'));
console.log(block.style.result);

true "--abstand" true 8px calc(var(--basis) * var(--faktor))

Aufteilung durch @media verstehen

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @function --textfarbe() {
    result: black;
    @media (prefers-color-scheme: dark) {
      result: white;
    }
  }
`);

const fnRule = sheet.cssRules[0];
for (const rule of fnRule.cssRules) {
  console.log(rule.constructor.name);
  if (rule instanceof CSSMediaRule) {
    const inner = rule.cssRules[0];
    console.log('  ->', inner.constructor.name, inner.style.result);
  }
}

CSSFunctionDeclarations CSSMediaRule -> CSSFunctionDeclarations white

result zur Laufzeit ändern (mit Feature-Erkennung)

const unterstuetzt = typeof CSSFunctionDeclarations !== 'undefined';

if (unterstuetzt) {
  const sheet = new CSSStyleSheet();
  sheet.replaceSync(`
    @function --radius() { result: 4px; }
    .karte { border-radius: --radius(); }
  `);
  document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

  const block = sheet.cssRules[0].cssRules[0];
  // Alle Elemente, die --radius() verwenden, werden neu berechnet
  block.style.setProperty('result', '12px');
  console.log(block.style.result);
} else {
  console.log('@function wird nicht unterstützt');
}

12px

// Wichtig · Fallstricke

Experimentelle Technologie: @function und die zugehörigen CSSOM-Interfaces gibt es bisher nur in Chromium-Browsern ab Version 139. Firefox und Safari unterstützen sie noch nicht. Prüfe vor der Nutzung mit typeof CSSFunctionDeclarations !== 'undefined' oder CSS.supports(), ob das Interface vorhanden ist. Unbekannte @function-Regeln verwirft der Parser, sie tauchen dann gar nicht in cssRules auf.

Ein Funktionskörper kann mehrere CSSFunctionDeclarations-Objekte enthalten. Jede Gruppenregel wie @media unterbricht die Folge. Verlasse dich also nicht darauf, dass cssRules[0] alle Deklarationen enthält.
Im style-Objekt sind nur Custom Properties (--*) und der Deskriptor result gültig. Normale CSS-Eigenschaften wie color werden beim Parsen ignoriert.
style selbst ist schreibgeschützt: Du kannst kein anderes Objekt zuweisen. Seinen Inhalt kannst du aber über setProperty() oder removeProperty() ändern.
Stylesheets von anderen Ursprüngen ohne CORS-Freigabe lösen beim Zugriff auf cssRules einen SecurityError aus.

Siehe auch

CSSFunctionRule CSSFunctionDescriptors CSSRule CSSStyleDeclaration CSSGroupingRule CSSStyleSheet CSSNestedDeclarations