Die@functionCSSat-rule ermöglicht das Definieren vonCSS-Benutzerfunktionen. Nach der Definition kann eine Benutzerfunktion mit der<dashed-function>-Syntax (zum Beispiel--my-function(30px, 3)) innerhalb eines beliebigen Eigenschaftswerts aufgerufen werden.

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 einem gültigen, benutzerdefinierten Identifier folgt. Er ist groß- und kleinschreibungssensitiv.

<function-parameter>#?Optional

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

--param-name

EinCSS-Benutzereigenschaft-Name zur Identifizierung des Parameters, ein<dashed-ident>, der mit-- beginnt und einem gültigen, benutzerdefinierten Identifier folgt. Er ist groß- und kleinschreibungssensitiv. Funktionsparameter können als benutzerdefinierte Eigenschaften betrachtet werden, die lokal auf den Funktionskörper beschränkt sind.

<css-type>Optional

Ein CSS-Datentyp oder einetype()-Funktion, die die akzeptierten Datentyp(en) für den Parameter definiert. Wenn dies nicht angegeben ist, ist jeder Datentyp für den Parameter gültig (entspricht der Angabetype(*)).

<default-value>Optional

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

[returns <css-type>]?Optional

Ein CSS-Datentyp oder einetype()-Funktion, vorangestellt mit dem Schlüsselwortreturns, die die akzeptierten Rückgabetyp(en) für den Parameter definiert. Wenn dies nicht angegeben ist, ist jeder Datentyp für den Parameter gültig (entspricht der Angabereturns type(*)), wobei beachtet werden sollte, dass die Funktion ungültig ist, wenn der Rückgabetyp nicht mit dem durch denresult-Deskriptor erzeugten Typ übereinstimmt.

<declaration-rule-list>

Eine oder mehrere CSS-Deklarationen oder At-Rules, die den Körper der Funktion definieren, der ihre Logik enthält. Eingeschlossene Deklarationen können umfassen:

• CSS-Benutzereigenschaften, die lokal auf den Funktionskörper beschränkt sind.
• Derresult-Deskriptor, entweder direkt innerhalb der@function-At-Rule oder innerhalb einer verschachtelten At-Rule.

Deskriptoren

result

Ein gültiger Eigenschaftswert, der das Ergebnis der zurückgegebenen CSS-Benutzerfunktion definiert. Der im Wert enthaltene Ausdruck wird ausgewertet und das Ergebnis wird zurückgegeben.

Beschreibung

CSS-Benutzerfunktionen ermöglichen das Definieren wiederverwendbarer Logikabschnitte, die abhängig von den als Eingabe akzeptierten Parametern und der im Funktionskörper 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 Benutzereigenschaften als Parameter,--color und--alpha, die lokal im Funktionskörper verwendet werden können. Der Körper enthält eine einzelne Zeile, die einresult-Deskriptor ist, der den von der Funktion zurückgegebenen Wert definiert. Der Wert desresult-Deskriptors verwendet dierelative CSS-Farbsyntax, um den Eingabewert--color in eineoklch()-Farbe mit dem in der Eingabe--alpha angegebenen Alphakanalwert zu konvertieren.

Sie können diese Funktion dann überall dort 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 Verwendung der<dashed-function>-Syntax aufgerufen, bei der es sich um den Funktionsnamen mit Klammern am Ende handelt. Die gewünschten Argumentwerte werden innerhalb der Klammern angegeben.

Datentypen angeben

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

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

Nun produziert die Funktion nur dann einen gültigen Wert, wenn die Eingabeargumente jeweils eine<color> und eine<number> sind und dasresult eine<color> ist. Wenn nicht, zum Beispiel:

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

dann wird der Wert zur Berechnungszeit ungültig (da das angegebene--alpha-Argument ein<percentage> ist und keine<number>, wie erwartet) und diebackground-color wird schließlich auftransparent gesetzt.

Sie können mehrere akzeptierte Datentypen mit einertype()-Funktion mit dem Symbol| als Trennzeichen 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 Aufruf der Funktion--transparent(var(--base-color), 50%) jetzt gültig.

Standardwerte angeben

Sie können auch Standardwerte für Parameter angeben, nach einem Doppelpunkt am Ende ihrer Definition. 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--alpha-Parameters ist jetzt0.8. Wenn Sie diesen Wert verwenden möchten, können Sie das zweite Argument beim Aufruf der Funktion weglassen:

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

Argumente mit Kommata als Argumente übergeben

Im nächsten Beispiel erwartet die Funktion--max-plus-x(), dass eine kommagetrennte Liste von Längen und eine einzelne Länge als Argumente übergeben werden. Sie verwendet die CSS-max()-Funktion, um zu bestimmen, welche der Listenlängen die größte 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 fehlinterpretiert werden könnte. Um dieses Problem zu umgehen, können Sie den Wert in geschweifte Klammern einbetten, wenn Sie ihn in den Funktionsaufruf übergeben:

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

Benutzerdefinierte Eigenschaften innerhalb von Funktionen einbinden

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

Sie können auch benutzerdefinierte Eigenschaften im Funktionskörper angeben, die als lokal begrenzte Konstanten fungieren. Im folgenden Beispiel definieren wir eine Funktion namens--anim-1s(), die einenanimation-Kurz notation-Wert zurückgibt, bei dem die Dauer und die Easing-Werte immer gleich sind und nur der Animationsname und die Anzahl variiert werden.

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

Diese Art der Verwendung ermöglicht es Ihnen, eine einfachere, ausdrucksstärkere Syntax für Animationen zu schreiben, vorausgesetzt, dass Sie wissen, dass Sie die Dauer und die Easing-Funktion immer gleich haben möchten:

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

Es ist auch erwähnenswert, dass Sie eine benutzerdefinierte Funktion von einer anderen Funktion aus aufrufen können. In solchen Fällen kann eine benutzerdefinierte Funktion auf lokale Variablen und Funktionsparameter von Funktionen im höheren Aufrufstack zugreifen. Hier stehen der Parameter und die lokale benutzerdefinierte Eigenschaft der äußeren Funktion im Bereich der inneren Funktion zur Verfügung:

@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, ihr zur Verfügung stehen:

@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 im Funktionskörper überschreiben beide. Im folgenden Beispiel verwendet die Funktion--add-a-b-c() die--a-Eigenschaft von der benutzerdefinierten Eigenschaft derdiv-Regel, die--b-Eigenschaft vom Funktionsparameter und die--c-lokale benutzerdefinierte Eigenschaft.

@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 */}

Komplexe Logik einbinden

Sie können komplexere Logik in Funktionen einbinden, indem Sie Konstrukte wie@media-At-Rules undif()-Funktionen verwenden. Zum Beispiel nimmt die nächste Funktion zwei Argumente, eines für ein Layout mit schmalem Bildschirm und eines für ein Layout mit breitem Bildschirm. Sie gibt letztere standardmäßig zurück, kehrt jedoch zur ersteren zurück, wenn die Ansichtbreite weniger als700px breit ist, was mit einer Media-Abfrage erkannt wird.

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

Sie können mehrereresult-Deskriptoren einfügen, um unterschiedliche Ergebnisse für verschiedene logische Ergebnisse auszudrücken.

Wir könnten die CSS-Benutzerfunktion umschreiben, um stattdessen eineif()-Funktion zu verwenden:

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

Formale Syntax

@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 unserenLeitfaden zur Verwendung von CSS-Benutzerfunktionen.

Grundlegende@function-Verwendung

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

HTML

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

<p>Some content</p>

CSS

In unseren Stilen definieren wir zuerst die CSS-Benutzerfunktion. Die Funktion heißt--double und akzeptiert einen einzelnen Parameter von beliebigem Typ, den wir--value genannt haben. Im Funktionskörper fügen wir einenresult-Deskriptor ein, der diecalc()-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 von10px. Wir weisen diesen Wert demborder-radius zu, verdoppeln ihn jedoch für denpadding-Wert mit der benutzerdefinierten Funktion--double().

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-Benutzereigenschaften
• <dashed-function> Datentyp
• type() Funktion
• Leitfaden zur Verwendung von CSS-Benutzerfunktionen
• CSS-Benutzerfunktionen und Mixins Modul