CSSFunctionDescriptors — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSFunctionDescriptors extends CSSStyleDeclaration

Beschreibung

Das Interface CSSFunctionDescriptors gehört zum CSS Object Model (CSSOM) und zur Spezifikation CSS Functions and Mixins. Es steht für die Deskriptoren in einem zusammenhängenden Block von Deklarationen innerhalb einer eigenen CSS-Funktion (@function --name(...) { ... }). Einen solchen Block stellt ein CSSFunctionDeclarations-Objekt dar. Über dessen Eigenschaft style erhältst du die zugehörige CSSFunctionDescriptors-Instanz.

CSSFunctionDescriptors erbt von CSSStyleDeclaration. Deshalb stehen die bekannten Methoden und Eigenschaften zur Verfügung, zum Beispiel getPropertyValue(), setProperty(), length, item() und cssText. Dazu kommt die eigene Eigenschaft result: Sie liefert den Wert des Deskriptors result als Zeichenkette, also den Ausdruck, den die Funktion zurückgibt. Lokale eigene Eigenschaften wie --x: ... im selben Block lassen sich ebenfalls über getPropertyValue() abfragen.

Einen Konstruktor gibt es nicht. Du bekommst Instanzen nur, wenn du ein Stylesheet mit @function-Regeln durchläufst: CSSFunctionRule → cssRules → CSSFunctionDeclarations → style. Das Interface ist vor allem für Werkzeuge nützlich, zum Beispiel für DevTools, Linter oder Theme-Editoren: Sie können damit eigene CSS-Funktionen zur Laufzeit untersuchen oder ändern.

Rückgabewert

Typ

CSSFunctionDescriptors

Beschreibung

Man erhält das Objekt über CSSFunctionDeclarations.style. Die wichtigste eigene Eigenschaft ist result (string).

Beispiele

Deskriptor result einer @function auslesen

// CSS im Dokument:
// @function --negativ(--wert) {
//   result: calc(-1 * var(--wert));
// }
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @function --negativ(--wert) {
    result: calc(-1 * var(--wert));
  }
`);

const funcRule = sheet.cssRules[0];          // CSSFunctionRule
const decls = funcRule.cssRules[0];           // CSSFunctionDeclarations
const descriptors = decls.style;              // CSSFunctionDescriptors

console.log(funcRule.name);
console.log(descriptors.result);

--negativ calc(-1 * var(--wert))

Alle Deskriptoren und lokalen Variablen auflisten

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @function --abstand(--faktor) {
    --basis: 8px;
    result: calc(var(--basis) * var(--faktor));
  }
`);

const { style } = sheet.cssRules[0].cssRules[0];

// Geerbt von CSSStyleDeclaration: length und item()
for (let i = 0; i < style.length; i++) {
  const name = style.item(i);
  console.log(`${name}: ${style.getPropertyValue(name)}`);
}

--basis: 8px result: calc(var(--basis) * var(--faktor))

Rückgabewert zur Laufzeit ändern (mit Feature-Erkennung)

if ('CSSFunctionDescriptors' in window) {
  const sheet = new CSSStyleSheet();
  sheet.replaceSync(`
    @function --akzent() { result: royalblue; }
    .box { background: --akzent(); }
  `);
  document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

  const descriptors = sheet.cssRules[0].cssRules[0].style;
  descriptors.setProperty('result', 'crimson'); // alle .box werden rot
  console.log(descriptors.result);
} else {
  console.log('@function wird nicht unterstützt');
}

crimson

// Wichtig · Fallstricke

Experimentell: @function und die zugehörigen CSSOM-Interfaces gibt es bisher nur in Chromium-Browsern (ab Version 139). Prüfe die Unterstützung mit 'CSSFunctionDescriptors' in window oder CSS.supports(), bevor du den Code im Produktivbetrieb einsetzt.
Die Eigenschaft result gibt den Ausdruck als Text zurück, nicht den berechneten Wert. Der berechnete Wert steht erst an der Stelle fest, an der die Funktion aufgerufen wird, und lässt sich dort per getComputedStyle() ermitteln.
Eine @function kann mehrere CSSFunctionDeclarations-Blöcke enthalten, etwa wenn @media- oder @supports-Regeln dazwischenstehen. Jeder dieser Blöcke hat ein eigenes CSSFunctionDescriptors-Objekt. Durchlaufe deshalb alle Einträge in cssRules und nicht nur den ersten.
Übliche CSS-Eigenschaften wie color sind in einer @function ungültig und werden verworfen. Erlaubt sind nur result und eigene Eigenschaften mit dem Präfix --.
Bei Stylesheets von fremden Domains ohne passende CORS-Freigabe löst der Zugriff auf cssRules einen SecurityError aus.

Siehe auch

CSSFontFaceDescriptors CSSFunctionDeclarations CSSPositionTryDescriptors CSSPageDescriptors CSSFunctionRule