Signatur
Beschreibung
Mit der CSS-At-Regel @function (Spezifikation „CSS Functions and Mixins“) lassen sich eigene CSS-Funktionen wie --double() festlegen. Den Wert, den eine solche Funktion liefert, gibt der Deskriptor result an. Im CSSOM wird die Regel als CSSFunctionRule abgebildet. Ihre Deklarationsblöcke erscheinen als CSSFunctionDeclarations-Objekte, und deren Eigenschaft style ist ein CSSFunctionDescriptors-Objekt.
Die Eigenschaft result dieses Objekts enthält den serialisierten Wert des result-Deskriptors als String, zum Beispiel "calc(var(--x) * 2)". Steht in diesem Deklarationsblock kein result, ist der Wert ein leerer String.
Nützlich ist die Eigenschaft für Werkzeuge, die Stylesheets untersuchen: Debugger, Linter, Design-Token-Werkzeuge oder Polyfills, die eigene CSS-Funktionen auslesen und auswerten. Weil CSSFunctionDescriptors von CSSStyleDeclaration erbt, bekommen Sie denselben Wert auch mit getPropertyValue("result").
Rückgabewert
result-Deskriptors, oder "", wenn im Deklarationsblock keiner festgelegt ist.Beispiele
result-Deskriptor einer @function-Regel auslesen
// Stylesheet mit einer eigenen CSS-Funktion einfügen
const style = document.createElement("style");
style.textContent = `
@function --double(--x) {
result: calc(var(--x) * 2);
}
`;
document.head.append(style);
const fnRule = style.sheet.cssRules[0]; // CSSFunctionRule
const declarations = fnRule.cssRules[0]; // CSSFunctionDeclarations
console.log(fnRule.name); // Name der Funktion
console.log(declarations.style.result); // CSSFunctionDescriptors.resultAlle eigenen CSS-Funktionen eines Dokuments auflisten
const listCssFunctions = () => {
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 (typeof CSSFunctionRule !== "undefined" && rule instanceof CSSFunctionRule) {
const results = [...rule.cssRules]
.filter((r) => r instanceof CSSFunctionDeclarations)
.map((r) => r.style.result)
.filter(Boolean);
result.push({ name: rule.name, results });
}
}
}
return result;
};
console.table(listCssFunctions());Funktionen erkennen und über getPropertyValue auslesen
if (!("CSSFunctionRule" in window)) {
console.warn("@function wird von diesem Browser nicht unterstützt.");
} else {
const sheet = new CSSStyleSheet();
sheet.replaceSync("@function --gap() { result: 1rem; }");
const descriptors = sheet.cssRules[0].cssRules[0].style;
console.log(descriptors.result); // direkter Zugriff
console.log(descriptors.getPropertyValue("result")); // gleichwertig
}// Wichtig · Fallstricke
- Experimentell:
@functionund die zugehörigen CSSOM-Schnittstellen gibt es bisher nur in Chromium-basierten Browsern (ab Version 139). Prüfen Sie vor der Nutzung mit"CSSFunctionRule" in window, ob die Funktion verfügbar ist. - Der Wert ist serialisiert: Leerzeichen und Schreibweise können vom Quelltext abweichen. Verlassen Sie sich nicht auf exakte String-Vergleiche mit dem Original.
var()-Bezüge und Argumente werden nicht aufgelöst. Sie erhalten den Ausdruck, nicht den berechneten Wert. Den berechneten Wert bekommen Sie übergetComputedStyle()auf einem Element, das die Funktion nutzt.- Eine Funktion kann mehrere Deklarationsblöcke haben, etwa innerhalb von
@mediaoder@supports. Jeder Block ist ein eigenesCSSFunctionDeclarations-Objekt mit eigenemresult. Welcher Wert gilt, hängt davon ab, welche Bedingungen gerade zutreffen. - Bei Stylesheets von fremden Ursprüngen ohne passende CORS-Freigabe löst der Zugriff auf
cssRuleseinenSecurityErroraus.