@function - Directive CSS

Description de la directive @function.

⚠

A l'heure actuelle (2025) la directive @function n'est reconnue que par les grands navigateurs suivants : Edge  , Chrome   et Android Browser  .

La directive @function permet de définir des fonctions personnalisées.
Prenons l'exemple suivant. Nous souhaitons ombrer le texte de la façon suivante : une première ombre colorée, éloignée de 5 pixels, et une deuxième ombre, en noir et éloignée de 10 pixels. Ce qui peut se réaliser avec le CSS suivant :

Si on souhaite changer juste la couleur de la première ombre sur un autre texte, il faut néanmoins répéter toute la syntaxe ci-dessus. Ce qui peut s'avérer assez fastidieux. Ou alors définir une fonction qui prendra en paramètre la couleur de la première ombre. Cette fonction pourra s'écrire de la façon suivante :

On notera plusieurs points :

• Le nom de la fonction est un identifiant précédé d'un double tiret.
• Il en est de même pour le paramètre (la couleur de la première bordure).
• La valeur du paramètre peut être récupérée avec la fonction var() comme n'importe quelle variable.
• Le résultat de la fonction est introduit par le mot result.

Il est maintenant plus facile d'ombrer nos textes :

⚠ Si cela ne marche pas comme vous voulez, essayez d'ouvrir cette page avec Chrome   ou Edge  .

Différences avec les propriétés personnalisées.

Les propriétés personnalisées sont encore appelée variables. La seule différence avec les fonctions personnalisées est que ces dernières sont paramétrables. Il est ainsi plus facile d'écrire du code ré-utilisable.

En rapport également avec les fonctions et propriétés personnalisées.

Syntaxes de la directive @function.

• @function --name(--prm1, --prm2 ...) { result: ... ; }

  Ceci est la structure d'une fonction personnalisée. --name est le nom de cette fonction. --prm1 et --prm2 sont les paramètres. Les doubles tirets au début de ces identifiants sont indispensables.

  Le résultat est décrit après le mot clé result. Le premier result rencontré ne met pas fin à la fonction, autrement dit, c'est toujours le dernier result rencontré qui est renvoyé. L'exemple ci-dessous montre une fonction mal écrite, qui renvoie toujours la même chose, que le navigateur soit compatible avec la fonction clamp() ou pas. Il aurait fallu écrire la ligne rayée au début de la fonction.

  @function --size(--min, --val, --max) { @support(width:clamp(var(--min), var(--val), var(--max))) { result: max(var(--min), min(val(--val), val(--max))); } result: clamp(var(--min), var(--val), var(--max)); }

  Les paramètres sont bien sûr local à la fonction (il n'est pas possible d'y accéder depuis l'extérieur de la fonction). Mais la fonction peut utiliser les propriétés personnalisées définies à l'extérieur de la fonction, avec var() (on les appelle aussi variables).

• @function --name(--prm1:value1, --prm2:value2 ...) { result: ... ; }

  Avec cette syntaxe, il est possible de définir une valeur par défaut pour chacun des paramètres. Ce qui permet, au moment d'utiliser la fonction de ne rien préciser dans les parenthèses (mais celles-ci sont néanmoins obligatoires).

• @function --name(--prm1 <type>, ...) returns <type> { result: ... ; }

  Ici nous définissons le type des paramètres d'entrée, et le type de la valeur de retour (avec le mot returns). L'indication d'un type est incompatible avec une valeur par défaut. Voici comment peuvent s'exprimer les types :

  <integer> : un type simple.
  type(<integer> | <number>) : énumération de types possibles, avec la fonction type().
  <integer>+ : une liste de valeurs du même type.

  Les types simples peuvent être, entre autres :

  <color>, <integer>, <length, <number>, <percentage>, etc.

Exemples d'utilisation de la directive @function.

⚠ Souvenez-vous que ces exemples ne marcheront pas sur tous les navigateurs.

Une fonction qui donne une couleur semi-transparente.

La fonction --opacity ci-dessous accepte une couleur en entrée et renvoie la même couleur avec une valeur de transparence. A défaut de ce deuxième paramètre, la transparence est fixée à 50%.

Tester le support d'une fonctionnalité.

Voici une fonction qui teste si le navigateur reconnaît la fonction clamp(); Si oui cette fonction est utilisée pour obtenir le résultat. Sinon la fonction personnalisée utilise la formule équivalente.

Simplifier les écritures.

Les fonctions peuvent être utilisés tout simplement pour simplifier les écritures. Par exemple, pour définir des arrondis d'angle, il est possible d'écrire une fonction qui accepte en paramètre seulement le premier arrondi, et qui calcule les autres.

Des tailles de polices qui s'adaptent.

Il est souvent utile d'adapter la taille des polices aux dimensions de l'écran : sur un gran écran (visible de loin), on peut souhaiter grossir la police, tandis que sur un petit écran, on essaiera plutôt de remettre une police normale.

Compatibilité des navigateurs avec la directive @function.

La directive @function est encore mal reconnue, en particulier par les grands navigateurs Firefox  , Opera   et Safari  .

1

Directive
@function

Estimation de la prise en charge globale.

64%

Navigateurs sur ordinateurs :

Navigateurs sur mobiles :

Navigateurs obsolètes ou marginaux :

Internet Explorer

UC Browser pour Androïd

Opéra Mobile

QQ Browser

Baidu Browser

Samsung Internet

Chrome

Edge

Safari

Opéra

Firefox

Chrome pour Androïd

Safari sur IOS

Androïd Brower

Firefox pour Androïd

KaiOS Browser

Opéra mini

Voir le site Caniuse.com pour plus d'informations de compatibilité.

Caniuse

Évolution de la directive @function.

• Module de fonctions CSS et de mixins CSS - Niveau 1.

  Introduction des fonctions CSS personnalisées dans ce premier niveau de la spécification.
  

  15 Mai 2025

  Document de travail.

  

  

  

Voir aussi, au sujet des fonctions personnalisées.

Voici le contenu du module CSS CSS Functions and Mixins Module.. On constate qu'il consiste essentiellement en la fonction @function.