@property - Directive CSS

@property

Résumé des caractéristiques de la directive @property

Description rapide
Définit une propriété personnalisée, avec sa valeur initiale, sa syntaxe et une indication sur l'héritage.
Statut
Standard
Module W3C
Module CSS - Propriétés et valeurs
Références (W3C)
Statut du document: WD (document de travail)

Description de la directive @property.

La descriptive @property autorise la déclaration d'une propriété personnalisée. En plus de la définition sans déclaration (voir var()) @property permet de spécifier une valeur initiale et l'héritage de la propriété personnalisée.

Exemple. Syntaxe sans déclaration :

:root { --bg-color:#ff8018; }

Le même exemple, déclaration avec @property :

@property --bg-color { syntax: '<color>'; initial-value: gray; inherits: false; } :root { --bg-color:#ff8018; }


Le fait de déclarer les propriétés personnalisées permet de les utiliser dans plus d'endroits. En particulier le fait de déclarer le type de données permet l'utilisation des propriétés personnalisées dans les animations.

Le premier example ci-dessous utilise une propriété personnalisée non déclarée (--angle1). On voit que l'animation se fait par saccades car le navigateur ne sait pas à quoi correspond angle1.
Dans le deuxième exemple, --angle2 est typé comme un angle et sa valeur initiale est 0deg : l'animation peut se faire.

Les propriétés personnalisées renvoient une valeur calculée, ce qui est également un facteur d'optimisation.

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

@property :
Définit une propriété personnalisée, avec sa valeur initiale, sa syntaxe et une indication sur l'héritage.
La directive @function définit une fonction personnalisée, avec ses paramètres.
Récupère la valeur d'une propriété personnalisée (variable).

Syntaxe de syntax.

  • @property --id { syntax: '<color>'; ... }

    Indique le type de donnée acceptée par la propriété personnalisés. Ce descripteur est obligatoire sinon toute la directive @property est invalide. C'est un mot entre < > et entre apostrophes (ou guillemets) qui peut être :

    • <angle> : une valeur d'angle (suivie d'une unités d'angle, ou une fonction qui renvoie un angle comme acos() par exemple.
    • <color> : une couleur exprimée dans n'importe laquelle des syntaxes reconnues par CSS, ou une fonction qui renvoie une couleur.
    • <custom-ident>: un identifiant personnalisé. Sensible à la casse.
    • <image> : une image ou une fonction qui renvoie une image.
    • <integer> : un nombre entier, sans virgule et sans unité.
    • <length> : une dimension, c'est à dire un nombre suivie d'une des unités de dimension, ou une fonction qui renvoie une dimension.
    • <length-percentage> : une dimension ou un pourcentage qui se résout en une dimension.
    • <number> : un nombre sans unité.
    • <percentage> : un pourcentage, c'est à dire une valeur suivie du signe %.
    • <resolution> : une valeur suivie d'une unités de résolution. Les unités de résolution sont plutôt utilisées dans les media-queries.
    • <string> : une chaîne de caractères, c'est à dire une suite de caractères entourés d'apostrophes ou de guillemets.
    • <time> : une valeur numérique suivie d'une unités de durée.
    • <transform-function> : une fonction de transformation : rotate(), scale(), skew(), translate(), matrix(), ou perspective(), ainsi que les variantes 3D de ces fonctions : rotateX(), rotateY(), rotateZ(), rotate3d(), scaleX(), scaleY(), scaleZ(), scale3d(), skewX(), skewY(), translateX(), translateY(), translateZ(), translate3d(), matrix3d();
    • <transform-list> : une liste de fonctions de transformation. Équivalent à <transform-function>+ .
    • <url> une URL définie par la fonction url() ou src().
    • * : n'importe quel type de données.
  • @property --id { syntax: '<color>+'; ... }

    Le signe + indique une série de valeurs séparées par un espace.
    Le signe * indique une série de valeurs séparées par une virgule.
    Le signe | indique une syntaxe multiple, qui peut accepter n'importe laquelle des syntaxes séparée par |.

    Exemple. Pour indiquer une propriété qui accepte un nombre entier ou une série de couleurs, écrivez :

    @property --id { syntax: '<integer> | <color>+' ; ... }
  • @property --id { syntax: 'auto | manual'; ... }

    Des mots non entourés de < > indiquent une propriété qui accepte ces mots là en tant que valeur.

Syntaxe de inherits.

  • @property --id { inherits: true; ... }

    Le descripteur inherits ne peut prendre que l'une des deux valeurs true ou false.
    true la propriété hérite par défaut.
    false la propriété n'hérite pas.

    Ce descripteur est obligatoire, sinon toute la directive @property est invalide.

Syntaxe de initial-value.

  • @property --id { initial-value: ...; ... }

    initial-value spécifie la valeur initiale de la propriété personnalisé. Elle doit bien sûr être conforme à ce qui est décrit dans syntax.
    Ce descripteur est également obligatoire.

Exemples d'utilisation de la directive @property.

Propriété non héritée par défaut.

La propriété à une valeur initiale égale à red et n'est pas héritée par défaut. On voit sur le premier exemple que c'est la valeur initiale qui est utilisée car la propriété, bien que définit sur la section, ne "descend" pas au niveau du titre. Il aurait fallu définir sa valeur également au niveau du titre, comme cela a été fait pour la section 2.

Titre de la section 1.

Texte de la section 1.

Titre de la section 2.

Texte de la section 2.

Propriété avec héritage par défaut.

Cette fois-ci la propriété est héritée par défaut, sa valeur initiale est toujours le rouge. Le premier exemple montre que la valeur descend au niveau du titre h4 pour la section 3. Dans la section 4, la valeur de --prop2 n'est pas définie. C'est donc la valeur initiale qui est utilisée.

Titre de la section 3.

Texte de la section 3.

Titre de la section 4.

Texte de la section 4.

Compatibilité des navigateurs avec la directive @property.

Colonne 1
Support des propriétés personnalisés (variables) et de la fonction var() qui permet de retrouver leur valeur.
Colonne 2
Support par les navigateurs de la directive @property qui permet de définir une propriété personnalisé, avec sa syntaxe, sa valeur initiale, et d'indiquer si elle hérite par défaut ou pas.
1
Propriété
personnalisées
2
Directive
@property
Estimation de la prise en charge globale.
96%
92%

Navigateurs sur ordinateurs :

Navigateurs sur mobiles :

Navigateurs obsolètes ou marginaux :

Internet Explorer

KaiOS Browser

Samsung Internet

Edge

Firefox

Androïd Brower

Chrome pour Androïd

Baidu Browser

QQ Browser

Safari

Safari sur IOS

Chrome

Opéra

Opéra Mobile

UC Browser pour Androïd

Firefox pour Androïd

Opéra mini

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

Évolution de la directive @property.

Voir aussi, à propos des propriétés personnalisées.

Les propriétés personnalisées, encore appelée variables, sont décrites dans le module de spécification CSS Properties and Values API.

    var() : Récupère la valeur d'une propriété personnalisée (variable).