@property
Baseline
2024
Newly available
Since July 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.
La règle @ CSS @property
fait partie de l'ensemble d'API CSS Houdini. Elle permet aux développeur·euse·s de définir explicitement des propriétés CSS personnalisées, avec vérification et contrainte de type, définition de valeurs par défaut et choix de l'héritage ou non de la propriété personnalisée.
La règle @property
permet d'enregistrer une propriété personnalisée directement dans une feuille de style, sans avoir à exécuter de JavaScript. Une règle @property
valide enregistre une propriété personnalisée, ce qui équivaut à appeler registerProperty()
avec des paramètres équivalents.
Syntaxe
@property --rotation {
syntax: "<angle>";
inherits: false;
initial-value: 45deg;
}
Le nom de la propriété personnalisée est un <dashed-ident>
qui commence par --
et est suivi d'un identifiant valide défini par l'utilisateur·ice. Il est sensible à la casse.
Descripteurs
Les conditions suivantes doivent être respectées pour que la règle @property
soit valide :
- La règle
@property
doit inclure les descripteurssyntax
etinherits
. Si l'un des deux manque, la règle entière est invalide et ignorée. - Le descripteur
initial-value
est optionnel si la valeur du descripteursyntax
est la définition universelle (syntax: "*"
). Si le descripteurinitial-value
est requis mais omis, la règle entière est invalide et ignorée. - Si la valeur du descripteur
syntax
n'est pas la définition universelle, le descripteurinitial-value
doit être une valeur indépendante du calcul(angl.). Cela signifie que la valeur peut être convertie en valeur calculée sans dépendre d'autres valeurs, sauf pour les définitions « globales » indépendantes de CSS. Par exemple,10px
est indépendant du calcul : il ne change pas lors de la conversion en valeur calculée.2in
est aussi valide, car1in
équivaut toujours à96px
. En revanche,3em
n'est pas valide, car la valeur d'unem
dépend de la propriétéfont-size
du parent. - Les descripteurs inconnus sont invalides et ignorés, mais n'invalident pas la règle
@property
.
Syntaxe formelle
@property =
@property <custom-property-name> { <declaration-list> }
Exemples
>Utiliser @property
pour enregistrer et utiliser une propriété personnalisée
Dans cet exemple, on définit deux propriétés personnalisées, --item-size
et --item-color
, qui serviront à définir la taille (largeur et hauteur) et la couleur d'arrière-plan des trois éléments suivants.
<div class="container">
<div class="item one">Élément un</div>
<div class="item two">Élément deux</div>
<div class="item three">Élément trois</div>
</div>
Le code suivant utilise la règle CSS @property
pour définir une propriété personnalisée nommée --item-size
. La propriété définit la valeur initiale à 40%
et limite les valeurs valides aux valeurs de type <percentage>
uniquement. Cela signifie que, lorsqu'elle est utilisée pour la taille d'un élément, sa taille sera toujours relative à celle de son parent. La propriété est héritée.
@property --item-size {
syntax: "<percentage>";
inherits: true;
initial-value: 40%;
}
On définit une seconde propriété personnalisée, --item-color
, en utilisant JavaScript au lieu de CSS. La méthode JavaScript registerProperty()
est équivalente à la règle @property
. La propriété est définie avec une valeur initiale aqua
, n'accepte que des valeurs de type <color>
, et n'est pas héritée.
window.CSS.registerProperty({
name: "--item-color",
syntax: "<color>",
inherits: false,
initialValue: "aqua",
});
On utilise les deux propriétés personnalisées pour mettre en forme les éléments :
.container {
display: flex;
height: 200px;
border: 1px dashed black;
/* valeurs des propriétés personnalisées sur le parent */
--item-size: 20%;
--item-color: orange;
}
/* utilisation des propriétés personnalisées pour la taille et la couleur d'arrière-plan */
.item {
width: var(--item-size);
height: var(--item-size);
background-color: var(--item-color);
}
/* valeurs des propriétés personnalisées sur l'élément lui-même */
.two {
--item-size: initial;
--item-color: inherit;
}
.three {
/* valeurs invalides */
--item-size: 1000px;
--item-color: xyz;
}
Les deux propriétés personnalisées, --item-size: 20%
et --item-color: orange;
, sont définies sur le parent container
, ce qui remplace les valeurs par défaut 40%
et aqua
définies lors de la création de ces propriétés. La taille est héritée, la couleur ne l'est pas.
Pour l'élément un, aucune de ces propriétés personnalisées n'a été définie. La propriété --item-size
est héritée, donc la valeur 20%
définie sur le parent container
est utilisée. En revanche, la propriété --item-color
n'est pas héritée, donc la valeur orange
du parent n'est pas prise en compte. À la place, la valeur initiale par défaut aqua
est utilisée.
Pour l'élément deux, des mots-clés globaux CSS sont définis pour les deux propriétés personnalisées, ce qui sont des valeurs valides pour tous les types et donc valides quel que soit le descripteur syntax
. La propriété --item-size
est définie sur initial
et utilise la valeur initial-value: 40%;
définie dans la déclaration @property
. La valeur initial
signifie que la valeur initialValue
de la propriété est utilisée. La propriété --item-color
est définie sur inherit
, héritant explicitement la valeur orange
du parent même si la propriété personnalisée n'est pas censée être héritée. C'est pourquoi l'élément deux est orange.
Pour l'élément trois, la valeur de --item-size
est définie sur 1000px
. Bien que 1000px
soit une valeur de type <length>
, la déclaration @property
exige une valeur de type <percentage>
, donc la déclaration est invalide et ignorée, ce qui fait que la valeur héritée 20%
du parent est utilisée. La valeur xyz
est également invalide. Comme registerProperty()
a défini --item-color
comme non héritée, la valeur initiale par défaut aqua
est utilisée et non la valeur orange
du parent.
Animer la valeur d'une propriété personnalisée
Dans cet exemple, on définit une propriété personnalisée appelée --progress
avec @property
: elle accepte des valeurs de type <percentage>
et a une valeur initiale de 25%
. On utilise --progress
pour définir la position des arrêts de couleur dans un linear-gradient()
, spécifiant où le vert s'arrête et où le noir commence. On anime ensuite la valeur de --progress
jusqu'à 100%
sur 2,5 secondes, ce qui donne l'effet d'une barre de progression animée.
<div class="bar"></div>
@property --progress {
syntax: "<percentage>";
inherits: false;
initial-value: 25%;
}
.bar {
display: inline-block;
--progress: 25%;
width: 100%;
height: 5px;
background: linear-gradient(
to right,
#00d230 var(--progress),
black var(--progress)
);
animation: progressAnimation 2.5s ease infinite;
}
@keyframes progressAnimation {
to {
--progress: 100%;
}
}
Spécifications
Specification |
---|
CSS Properties and Values API Level 1> # at-property-rule> |
Compatibilité des navigateurs
Loading…