CSSFunctionRule.getParameters() — Methode · JavaScript-Referenz

Signatur

CSSFunctionRule.prototype.getParameters()

Beschreibung

Die Methode getParameters() des Interfaces CSSFunctionRule liest die Parameterliste einer benutzerdefinierten CSS-Funktion aus, die mit der At-Regel @function definiert wurde (Spezifikation CSS Functions and Mixins). Jeder Parameter wird als einfaches Objekt (Dictionary FunctionParameter) mit den Eigenschaften name, type und defaultValue zurückgegeben.

Nützlich ist die Methode, wenn man Stylesheets per CSSOM untersucht, z. B. für Entwicklerwerkzeuge, Design-System-Dokumentation, Linter oder Tests. Damit lässt sich prüfen, welche Argumente eine Funktion wie --lighter() erwartet, welche Typen erlaubt sind und welche Parameter optional sind, weil sie einen Standardwert haben.

Die Werte kommen als serialisierte Zeichenketten zurück, also so, wie der Browser sie normalisiert hat, und nicht unbedingt exakt so, wie sie im Quelltext stehen. Ist kein Typ angegeben, lautet type "*". Fehlt ein Standardwert, ist defaultValue null. Jeder Aufruf liefert ein neues Array. Änderungen daran wirken sich nicht auf die Regel aus.

Rückgabewert

Typ

Array<{ name: string, type: string, defaultValue: string | null }>

Beschreibung

Ein Array mit einem Objekt pro Parameter, in der Reihenfolge der Deklaration:

name: Name des Parameters inklusive ---Präfix, z. B. "--color".
type: Typangabe als String, z. B. "<color>", "type(<length> | <percentage>)" oder "*", wenn kein Typ angegeben ist.
defaultValue: serialisierter Standardwert oder null.

Hat die Funktion keine Parameter, ist das Array leer.

Beispiele

Parameter einer @function-Regel auslesen

// CSS im Dokument:
// @function --lighter(--color <color>, --amount <number>: 0.2) returns <color> {
//   result: oklch(from var(--color) calc(l + var(--amount)) c h);
// }

const sheet = document.styleSheets[0];
const fnRule = [...sheet.cssRules].find(
  (rule) => rule instanceof CSSFunctionRule && rule.name === '--lighter'
);

console.log(fnRule.getParameters());

[ { name: "--color", type: "<color>", defaultValue: null }, { name: "--amount", type: "<number>", defaultValue: "0.2" } ]

Pflicht- und optionale Parameter unterscheiden

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @function --space(--step <integer>, --base <length>: 4px, --unit) {
    result: calc(var(--step) * var(--base));
  }
`);

const [rule] = sheet.cssRules;
const params = rule.getParameters();

const required = params.filter((p) => p.defaultValue === null).map((p) => p.name);
const optional = params.filter((p) => p.defaultValue !== null).map((p) => p.name);

console.log('Pflicht:', required);
console.log('Optional:', optional);
console.log('Typ von --unit:', params[2].type);

Pflicht: ["--step", "--unit"] Optional: ["--base"] Typ von --unit: *

Signaturen aller CSS-Funktionen dokumentieren (mit Feature-Erkennung)

const describeCssFunctions = () => {
  if (typeof CSSFunctionRule === 'undefined') {
    console.warn('@function wird von diesem Browser nicht unterstützt.');
    return [];
  }

  const signatures = [];
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // kann bei fremden Stylesheets (CORS) werfen
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (!(rule instanceof CSSFunctionRule)) continue;
      const args = rule.getParameters()
        .map(({ name, type, defaultValue }) =>
          `${name} ${type}${defaultValue !== null ? `: ${defaultValue}` : ''}`)
        .join(', ');
      signatures.push(`${rule.name}(${args}) returns ${rule.returnType}`);
    }
  }
  return signatures;
};

console.log(describeCssFunctions());

["--lighter(--color <color>, --amount <number>: 0.2) returns <color>"]

// Wichtig · Fallstricke

Experimentelle API: @function und CSSFunctionRule werden derzeit nur von Chromium-Browsern unterstützt (ab Version 139). Vor der Nutzung sollte man mit typeof CSSFunctionRule !== 'undefined' prüfen, ob die API vorhanden ist. In anderen Browsern wird die @function-Regel beim Parsen verworfen und taucht in cssRules gar nicht auf.
Nur lesend: Parameter lassen sich über das zurückgegebene Array nicht ändern. Um die Signatur zu ändern, muss man die Regel austauschen, z. B. mit deleteRule()/insertRule() oder replaceSync().
Serialisierung: type und defaultValue sind normalisierte Strings. Leerzeichen, Groß-/Kleinschreibung oder Schreibweisen wie type(…) können vom Quelltext abweichen. Deshalb nicht auf exakte Textgleichheit mit dem Original verlassen.
Fehlender Typ: Ohne Typangabe liefert type den Wert "*" (beliebiger Typ) und nicht null oder einen leeren String.
CORS: Wer cssRules von Stylesheets anderer Herkunft ohne passende CORS-Header liest, löst einen SecurityError aus. Deshalb in try/catch einschließen.

Siehe auch

CSSFunctionRule CSSFunctionRule.name CSSFunctionRule.returnType CSSFunctionDeclarations CSSGroupingRule CSSStyleSheet.cssRules CSSPropertyRule