@function

Syntax

@function --function-name(<function-parameter>#?) [returns <css-type>]? {
  <declaration-rule-list>
}

<function-parameter> = --param-name <css-type>? [ : <default-value> ]?

Die verschiedenen Teile der @function-Syntax sind wie folgt:

--function-name

Der identifizierende Name der Funktion, ein <dashed-ident>, der mit -- beginnt und von einem gültigen, benutzerdefinierten Bezeichner gefolgt wird. Er ist groß- und kleinschreibungsempfindlich.

<function-parameter>#? Optional

Null oder mehr Funktionsparameterdefinitionen. Mehrere Parameterdefinitionen werden durch Kommas getrennt. Jeder Parameter besteht aus:

--param-name

Ein CSS benutzerdefiniertes Eigenschaft Name zur Identifizierung des Parameters, ein <dashed-ident>, der mit -- beginnt und von einem gültigen, benutzerdefinierten Bezeichner gefolgt wird. Er ist groß- und kleinschreibungsempfindlich. Funktionsparameter können als benutzerdefinierte Eigenschaften betrachtet werden, die lokal auf den Funktionskörper beschränkt sind.

<css-type> Optional

Ein CSS-Datentyp oder eine type() Funktion, die die akzeptierten Datentypen für den Parameter definiert. Wenn dies nicht angegeben ist, wird jeder Datentyp als gültig für den Parameter angesehen (ebenso wie die Angabe von type(*)).

<default-value> Optional

Ein CSS-Wert, der den Standardwert angibt, der dem Parameter zugewiesen wird, wenn er nicht beim Aufruf der Funktion angegeben wird. Dieser Wert muss gemäß dem <css-type>, falls angegeben, gültig sein. Der Standardwert wird durch einen Doppelpunkt (:) von den anderen Teilen der Parameterdefinition getrennt.

[returns <css-type>]? Optional

Ein CSS-Datentyp oder eine type() Funktion, vorangestellt durch das Schlüsselwort returns, die die akzeptierten Rückgabetypen für den Parameter definiert. Wenn dies nicht angegeben ist, wird jeder Datentyp als gültig für den Parameter angesehen (ebenso wie die Angabe von returns type(*)), wobei zu beachten ist, dass die Funktion ungültig wird, wenn der Rückgabewert nicht dem Typ entspricht, der durch den result Deskriptor erzeugt wird.

<declaration-rule-list>

Eine oder mehrere CSS-Deklarationen oder At-Regeln, die den Funktionskörper definieren und die Logik enthalten. Eingeschlossene Deklarationen können enthalten:

• CSS benutzerdefinierte Eigenschaften, die lokal auf den Funktionskörper beschränkt sind.
• Der result Deskriptor, entweder direkt innerhalb der @function At-Regel oder innerhalb einer verschachtelten At-Regel.

Deskriptoren

result

Ein gültiger Eigenschaftswert, der das Ergebnis definiert, das von der CSS benutzerdefinierten Funktion zurückgegeben wird. Der Ausdruck im Wert wird ausgewertet und das Ergebnis zurückgegeben.

Beschreibung

CSS benutzerdefinierte Funktionen ermöglichen es Ihnen, wiederverwendbare Logikabschnitte zu definieren, die je nach den als Eingaben akzeptierten Parametern und der innerhalb des Funktionskörpers definierten Logik unterschiedliche Werte zurückgeben.

Eine typische CSS-Funktion sieht so aus:

@function --transparent(--color, --alpha) {
  result: oklch(from var(--color) l c h / var(--alpha));
}

Die Funktion hat den Namen --transparent und nimmt zwei benutzerdefinierte Eigenschaften als Parameter an, --color und --alpha, die lokal im Funktionskörper verwendet werden können. Der Körper enthält eine einzige Zeile, die ein result Deskriptor ist, der den Wert definiert, der von der Funktion zurückgegeben wird. Der Wert des result Deskriptors verwendet die CSS relative Farbensyntax, um den Eingabewert --color in eine oklch() Farbe mit dem im Eingabewert --alpha angegebenen Alphakanalwert zu konvertieren.

Sie können diese Funktion dann überall aufrufen, wo Sie eine halbtransparente Version einer vorhandenen Farbe erzeugen möchten, zum Beispiel:

section {
  --base-color: #faa6ff;
  background-color: --transparent(var(--base-color), 0.8);
}

Die Funktion wird durch die Verwendung der <dashed-function>-Syntax aufgerufen, das ist der Funktionsname mit Klammern am Ende. Die gewünschten Argumentwerte werden innerhalb der Klammern angegeben.

Festlegen von Datentypen

Es ist möglich, Datentypen für die Funktionsparameter und Rückgabetypen festzulegen. Zum Beispiel:

@function --transparent(--color <color>, --alpha <number>) returns <color> {
  result: oklch(from var(--color) l c h / var(--alpha));
}

Jetzt erzeugt die Funktion nur dann einen gültigen Wert, wenn die Eingabewerte ein <color> und ein <number> sind, und der result ein <color> ist. Wenn nicht, zum Beispiel:

section {
  --base-color: #faa6ff;
  background-color: --transparent(var(--base-color), 50%);
}

wird der Wert zur Berechnungszeit ungültig (weil das angegebene --alpha-Argument ein <percentage> und nicht eine <number> ist) und die background-color wird schließlich auf transparent gesetzt.

Sie können mehrere akzeptierte Datentypen mit einer type() Funktion mit dem | Symbol als Separator angeben, zum Beispiel:

@function --transparent(--color <color>, --alpha type(<number> | <percentage>))
  returns <color> {
  result: oklch(from var(--color) l c h / var(--alpha));
}

Mit dieser Anpassung ist der Funktionsaufruf --transparent(var(--base-color), 50%) nun gültig.

Angabe von Standardwerten

Sie können auch Standardwerte für Parameter am Ende ihrer Definition nach einem Doppelpunkt angeben. Zum Beispiel:

@function --transparent(--color <color>, --alpha <number>: 0.8) returns <color> {
  result: oklch(from var(--color) l c h / var(--alpha));
}

Der Standardwert des Parameters --alpha ist nun 0.8. Wenn Sie diesen Wert verwenden möchten, können Sie das zweite Argument beim Funktionsaufruf weglassen:

section {
  --base-color: #faa6ff;
  background-color: --transparent(var(--base-color));
}

Übergabe von Werten, die Kommas enthalten, als Argumente

Im nächsten Beispiel erwartet die Funktion --max-plus-x(), dass ihr eine kommagetrennte Liste von Längen und eine einzelne Länge als Argumente übergeben werden. Sie verwendet die CSS max() Funktion, um zu bestimmen, welches der Listen von Längen am größten ist, addiert sie zur einzelnen Länge, und gibt das Ergebnis zurück.

@function --max-plus-x(--list <length>#, --x <length>) {
  result: calc(max(var(--list)) + var(--x));
}

Das erste Argument muss eine kommagetrennte Liste sein, die als drei separate Argumente missverstanden werden könnte. Um dieses Problem zu umgehen, können Sie den Wert in geschweifte Klammern einschließen, wenn Sie ihn in den Funktionsaufruf übergeben:

div {
  width: --max-plus-x({1px, 7px, 2px}, 3px); /* 10px */
}

Einbeziehung benutzerdefinierter Eigenschaften in Funktionen

Wie wir bereits gesehen haben, werden Funktionsparameter als benutzerdefinierte Eigenschaften definiert, die dann im Funktionskörper verfügbar sind.

Sie können auch benutzerdefinierte Eigenschaften im Funktionskörper angeben, die als lokal-gescopedte Konstanten fungieren. Im folgenden Beispiel definieren wir eine Funktion namens --anim-1s(), die einen animation-Shortcode-Wert zurückgibt, bei dem die Dauer- und Überblendenwerte immer gleich bleiben, und nur der Animationsname und die Zählung variiert werden.

@function --anim-1s(--animation, --count) {
  --duration: 1s;
  --easing: linear;
  result: var(--animation) var(--duration) var(--count) var(--easing);
}

Diese Art der Nutzung ermöglicht es Ihnen, eine einfachere, ausdrucksstärkere Syntax für Animationen zu schreiben, vorausgesetzt, Sie wissen, dass Sie immer dieselbe Dauer und Überblendenfunktion verwenden wollen:

animation: --anim-1s(bounce, 2);

Es ist auch erwähnenswert, dass Sie eine benutzerdefinierte Funktion von einer anderen aus aufrufen können. In solchen Fällen kann eine benutzerdefinierte Funktion auf lokale Variablen und Funktionsparameter von Funktionen höher im Aufrufstack zugreifen. Hier wird der Parameter der äußeren Funktion und die lokale benutzerdefinierte Eigenschaft im Gültigkeitsbereich der inneren Funktion verfügbar sein:

@function --outer(--outer-arg) {
  --outer-local: 2;
  result: --inner();
}

@function --inner() returns <number> {
  result: calc(var(--outer-arg) + var(--outer-local));
}

div {
  z-index: --outer(1); /* 3 */
}

Zusätzlich werden benutzerdefinierte Eigenschaften, die auf demselben Element definiert sind, auf dem die benutzerdefinierte Funktion aufgerufen wird, verfügbar sein:

@function --double-z() returns <number> {
  result: calc(var(--z) * 2);
}

div {
  --z: 3;
  z-index: --double-z(); /* 6 */
}

Wenn eine benutzerdefinierte Eigenschaft mit demselben Namen an mehreren Stellen definiert ist, überschreiben Funktionsparameter benutzerdefinierte Eigenschaften, die auf demselben Element definiert sind, und lokal definierte benutzerdefinierte Eigenschaften innerhalb des Funktionskörpers überschreiben beides. Im folgenden Beispiel verwendet die Funktion --add-a-b-c() die Eigenschaft --a aus der benutzerdefinierten Eigenschaft der div-Regel, die Eigenschaft --b aus dem Funktionsparameter und die lokal definierte benutzerdefinierte Eigenschaft --c.

@function --add-a-b-c(--b, --c) {
  --c: 300;
  result: calc(var(--a) + var(--b) + var(--c));
}

div {
  --a: 1;
  --b: 2;
  --c: 3;
  z-index: --add-a-b-c(20, 30); /* 321 */
}

Einbeziehung komplexer Logik

Sie können komplexere Logik in Funktionen mit Konstrukten wie @media At-Regeln und if() Funktionen einbeziehen. Zum Beispiel nimmt die nächste Funktion zwei Argumente, eines für ein Layout mit schmalem Bildschirm und eines für ein Layout mit großem Bildschirm. Sie gibt standardmäßig letzteres zurück, gibt aber ersteres zurück, wenn die Viewport-Breite weniger als 700px breit ist, wie durch eine Medienabfrage erkannt wird.

@function --narrow-wide(--narrow, --wide) {
  result: var(--wide);
  @media (width < 700px) {
    result: var(--narrow);
  }
}

Sie können mehrere result Deskriptoren einbeziehen, um unterschiedliche Ergebnisse für verschiedene Logikausgänge auszudrücken.

Wir könnten die CSS benutzerdefinierte Funktion umschreiben, um eine if()-Funktion zu verwenden:

@function --narrow-wide(--narrow, --wide) {
  result: if(media(width < 700px): var(--narrow) ; else: var(--wide));
}

Formalsyntax

@function = 
  @function <function-token> <function-parameter>#? ) [ returns <css-type> ]? { <declaration-rule-list> }  

<function-parameter> = 
  <custom-property-name> <css-type>? [ : <default-value> ]?  

<css-type> = 
  <syntax-component>  |
  <type()>            

<default-value> = 
  <declaration-value>  

<syntax-component> = 
  <syntax-single-component> <syntax-multiplier>?  |
  '<' transform-list '>'                          

<type()> = 
  type( <string> )  

<syntax-single-component> = 
  '<' <syntax-type-name> '>'  |
  <ident>                     

<syntax-multiplier> = 
  '#'  |
  '+'  

<syntax-type-name> = 
  angle               |
  color               |
  custom-ident        |
  image               |
  integer             |
  length              |
  length-percentage   |
  number              |
  percentage          |
  resolution          |
  string              |
  time                |
  url                 |
  transform-function  

Beispiele

Für weitere Beispiele siehe unseren Using CSS custom functions Leitfaden.

Grundlegende Verwendung von @function

Dieses Beispiel zeigt eine grundlegende Funktion, die den Wert verdoppelt, der in sie übergeben wird.

HTML

Das Markup enthält ein <p>-Element mit einigen Textinhalten:

<p>Some content</p>

CSS

In unseren Styles definieren wir zunächst die CSS benutzerdefinierte Funktion. Die Funktion heißt --double und akzeptiert einen einzigen Parameter vom beliebigen Typ, den wir --value genannt haben. Im Funktionskörper fügen wir einen result Deskriptor ein, der die calc()-Funktion verwendet, um das übergebene Argument zu verdoppeln:

@function --double(--value) {
  result: calc(var(--value) * 2);
}

Als Nächstes definieren wir eine benutzerdefinierte Eigenschaft --base-spacing mit einem Wert von 10px. Wir weisen diese Eigenschaft dem border-radius Wert zu, verdoppeln sie dann aber für den padding Wert mit der --double() benutzerdefinierten Funktion.

html,
body {
  height: 100%;
}

body {
  margin: 0;
  display: grid;
  place-items: center;
  font-family: system-ui;
}

p {
  --base-spacing: 10px;
  border-radius: var(--base-spacing);
  padding: --double(var(--base-spacing));
  width: 50%;
  background-color: wheat;
}

Ergebnis

Spezifikationen

Browser-Kompatibilität

Siehe auch

• CSS benutzerdefinierte Eigenschaften
• <dashed-function> Datentyp
• type() Funktion
• Using CSS custom functions
• CSS benutzerdefinierte Funktionen und Mixins Modul