Signatur
Beschreibung
Die Schnittstelle CSSFunctionRule gehört zum CSS-Objektmodell (CSSOM) und steht für eine @function-At-Regel. Damit lassen sich in CSS eigene Funktionen wie --opacity(--color, --alpha) definieren, die Parameter entgegennehmen und über den Deskriptor result einen Wert zurückgeben. Sobald ein Stylesheet mit einer solchen Regel geladen ist, taucht sie in CSSStyleSheet.cssRules als CSSFunctionRule-Objekt auf.
Die Schnittstelle erbt von CSSGroupingRule (und damit von CSSRule). Sie hat folgende eigene Mitglieder:
name(nur lesbar,string): der Name der Funktion inklusive der beiden Bindestriche, z. B."--opacity".returnType(nur lesbar,string): der deklarierte Rückgabetyp, z. B."<color>"; ohnereturns-Angabe"*".getParameters(): liefert ein Array von Objekten mit den Feldernname,typeunddefaultValue(stringodernull) – eines pro deklariertem Parameter.
Über das geerbte cssRules kommt man an den Rumpf der Funktion. Dort liegen CSSFunctionDeclarations-Objekte, deren style-Eigenschaft (ein CSSFunctionDescriptors-Objekt) den result-Wert enthält, außerdem verschachtelte bedingte Regeln wie @media oder @supports.
Brauchen wirst du die Schnittstelle vor allem für Werkzeuge, die Stylesheets untersuchen: Debugging-Tools, Linter, Design-System-Dokumentation oder Code, der zur Laufzeit prüft, welche benutzerdefinierten Funktionen es gibt und welche Signatur sie haben.
Rückgabewert
Beispiele
Alle @function-Regeln eines Dokuments auflisten
// Voraussetzung im CSS:
// @function --opacity(--color <color>, --alpha <number>: 0.5) returns <color> {
// result: rgb(from var(--color) r g b / var(--alpha));
// }
const listCustomFunctions = () => {
if (typeof CSSFunctionRule === 'undefined') {
console.warn('@function wird von diesem Browser nicht unterstützt.');
return [];
}
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 CSSFunctionRule) {
result.push(`${rule.name} → ${rule.returnType}`);
}
}
}
return result;
};
console.log(listCustomFunctions());Parameter einer Funktion mit getParameters() auslesen
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
@function --spacing(--factor <number>: 1, --base) returns <length> {
result: calc(var(--factor) * 8px);
}
`);
const rule = sheet.cssRules[0];
if (rule instanceof CSSFunctionRule) {
console.log(rule.name);
console.log(rule.returnType);
for (const { name, type, defaultValue } of rule.getParameters()) {
console.log(`${name}: ${type} (Standard: ${defaultValue ?? 'keiner'})`);
}
}result-Deskriptor im Funktionsrumpf lesen
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
@function --double(--x) {
result: calc(var(--x) * 2);
}
`);
const fnRule = sheet.cssRules[0];
for (const inner of fnRule.cssRules) {
// CSSFunctionDeclarations enthält die Deskriptoren
if (inner.style) {
console.log('result =', inner.style.result);
}
}// Wichtig · Fallstricke
- Kompatibilität:
@functionundCSSFunctionRulesind experimentell. Bisher unterstützen nur Chromium-Browser sie (ab Version 139). Firefox und Safari kennen sie noch nicht. Prüfe deshalb vorher mittypeof CSSFunctionRule !== 'undefined'oder in CSS mit@supports, ob sie verfügbar sind. - Browser ohne Unterstützung verwerfen die Regel beim Parsen. Sie erscheint dann gar nicht in
cssRules, es wird also auch keine andere Regel an ihrer Stelle angelegt. nameundreturnTypesind nur lesbar. Um eine Funktion zu ändern, musst du die Regel mitdeleteRule()entfernen und mitinsertRule()neu einfügen.- Der Funktionsname muss mit
--beginnen, genau wie bei benutzerdefinierten Eigenschaften. Ohne Typangabe liefertgetParameters()den Typ"*". - Stylesheets von fremden Ursprüngen ohne passende CORS-Header werfen beim Zugriff auf
cssRuleseinenSecurityError. Fange diesen Fehler ab. - Die Spezifikation (CSS Mixins and Functions) ist noch im Entwurf. Namen und Rückgabeformen einzelner Mitglieder können sich noch ändern.