Proprit CSS mask-position

Syntaxe

/* Valeurs avec un mot-cl de type <position> */
/* Dfinit la deuxime valeur  'center' */
mask-position: left;
mask-position: center;
mask-position: right;
mask-position: top;
mask-position: bottom;

/* Valeurs avec deux mots-cls de type <position> */
mask-position: left center;
mask-position: right top;

/* Une valeur de type <position> en longueur ou pourcentage */
/* Position horizontale. Position verticale dfinie  'center' */
mask-position: 25%;
mask-position: 0px;
mask-position: 8em;

/* Deux valeurs de type <position> en longueur ou pourcentage */
/* Premire valeur : position horizontale. Deuxime valeur : position verticale */
mask-position: 25% 75%;
mask-position: 0px 0px;
mask-position: 10% 8em;

/* Dcalages par rapport aux bords : Quatre valeurs de type <position> */
mask-position: bottom 10px right 20px;
mask-position: right 3em bottom 10px;
mask-position: bottom 10px right 0;

/* Plusieurs valeurs de type <position> */
mask-position:
  top left,
  bottom 10px right 10px;
mask-position:
  1rem 1rem,
  center;

/* Valeurs globales */
mask-position: inherit;
mask-position: initial;
mask-position: revert;
mask-position: revert-layer;
mask-position: unset;

Valeurs

Une ou plusieurs valeurs de type <position>, spares par des virgules.

<position>

Une, deux ou quatre valeurs reprsentant une position 2D dfinissant les bords de la bote de l'lment. Des dcalages relatifs ou absolus peuvent tre donns.

Description

La proprit mask-position dfinit la position de chaque calque de masque. Un lment peut avoir plusieurs calques de masque appliqus. Le nombre de calques est dtermin par le nombre de valeurs spares par des virgules dans la valeur de la proprit mask-image (mme les valeurs none crent un calque).

Chaque valeur mask-position dans la liste de valeurs spares par des virgules est associe un calque de masque correspondant, comme dfini par la liste des valeurs mask-image, dans l'ordre. Si le nombre de valeurs dans les deux proprits diffre :

• Si mask-position a plus de valeurs que mask-image, les valeurs excdentaires de mask-position ne sont pas utilises.
• Si mask-position a moins de valeurs que mask-image, les valeurs de mask-position sont rptes.

Chaque mask-position dfinit la position du calque de masque associ par rapport la valeur mask-origin associe. Les valeurs de la proprit mask-origin sont galement associes aux valeurs de mask-image, dans l'ordre, les valeurs excdentaires de mask-position tant inutilises ou les valeurs de mask-position tant rptes si elles sont moins nombreuses que les valeurs de mask-origin. Chaque calque de masque a donc une valeur mask-origin et mask-position associe.

Si aucun mask-origin n'est dfini, la valeur par dfaut est padding-box, ce qui signifie que l'origine de chaque mask-position est le remplissage de la bote de l'lment.

Syntaxe une valeur

Si une seule valeur mask-position est dfinie, la deuxime valeur est suppose tre center. Si la valeur est une <length> ou un <percentage>, elle dfinit la position du masque le long de l'axe horizontal, le masque tant centr verticalement dans la bote d'origine. Par exemple, mask-position: 0%; quivaut mask-position: 0% center.

Si vous utilisez un seul mot-cl pour le positionnement, l'autre valeur sera rsolue en center. La valeur par dfaut de mask-position est 0% 0%, ce qui quivaut mask-position: top left. Cependant :

• mask-position: top; est quivalent mask-position: top center;.
• mask-position: left; est quivalent mask-position: center left.
• mask-position: center; est quivalent mask-position: center center.

Si la valeur est une valeur de type <length>, elle reprsente la position horizontale comme un dcalage par rapport au bord gauche du positionnement du masque. Une valeur positive reprsente un dcalage vers l'intrieur partir du bord gauche du conteneur de la bote. La position peut tre dfinie en dehors de la bote de l'lment en utilisant une valeur ngative cela cre un dcalage vers l'extrieur qui place l'lment en dehors du bord gauche du conteneur.

Valeurs en pourcentage

Une valeur de type <percentage> reprsente la position horizontale du masque par rapport la largeur du conteneur, positionne par rapport au bord gauche. Cependant, le dcalage ne se fait pas du bord du masque au bord de la bote. Au lieu de cela, la dimension de l'image du masque est soustraite de la dimension du conteneur, puis un pourcentage de la valeur rsultante est utilis comme dcalage direct partir du bord gauche de la bote, ce qui est identique aux valeurs en pourcentage pour background-position.

L'quation est :

(dimension du conteneur - dimension du masque) * position en pourcentage = valeur de dcalage

tant donn un masque de 100px de large et une bote d'origine de 1000px de large, dfinir mask-position: 10%; (l'quivalent de 10% 50%) entrane le centrage vertical du masque 90px du bord gauche. L'quation est (1000 - 100) * 10% = 90. Si le dcalage gauche avait t 0%, le bord gauche du masque serait align avec le bord gauche du conteneur ((1000 - 100) * 0% = 0).

Si le dcalage gauche avait t 100%, le bord droit du masque serait align avec le bord droit du conteneur, car le bord gauche du masque de 100px de large serait 900px ((1000 - 100) * 100% = 900) du bord gauche du conteneur (la largeur du masque de 100px plus la distance de 900px depuis le bord gauche signifie que le bord droit serait 1000px du bord gauche, ce qui correspond au bord droit du conteneur).

Syntaxe deux valeurs

Une <position> deux valeurs dfinit la position de l'image du masque l'intrieur de sa zone de positionnement, les valeurs de longueur et de pourcentage dfinissant les dcalages par rapport au left et au top de la zone.

Si les deux valeurs sont des valeurs de type <length>, des valeurs de type <percentage> ou le mot-cl center, la premire valeur reprsente la position horizontale comme un dcalage par rapport au bord gauche de la zone de positionnement du masque, et la deuxime valeur reprsente la position verticale comme un dcalage par rapport au bord suprieur, avec les pourcentages tant dcals par la taille du masque dans cette dimension.

De plus, si des valeurs de type <percentage> sont dfinies, la premire valeur reprsente galement la position horizontale par rapport au bord gauche, et la deuxime valeur reprsente galement la position verticale par rapport au bord suprieur.

Une paire de mots-cls spcifiques un axe peut tre rordonne, tout comme un mot-cl spcifique un axe et une valeur de longueur ou de pourcentage, mais deux valeurs de longueur ou de pourcentage ne sont pas interchangeables. Si l'une des deux valeurs est top, right, bottom ou left, l'ordre des deux valeurs n'a pas d'importance. Toute valeur center ou <length-percentage> dans la paire de valeurs sera applique l'autre dimension.

Syntaxe quatre valeurs

La syntaxe quatre valeurs consiste en deux paires de valeurs, chaque paire contenant un mot-cl dfinissant le bord partir duquel dcaler, et une valeur <length> et <percentage> dfinissant la distance de dcalage. Par exemple, mask-position: left 1em top 2em dfinit un dcalage horizontal de 1em partir du bord gauche de la bote et un dcalage vertical de 2em partir du bord suprieur. L'quivalent deux valeurs serait mask-position: 1em 2em.

Comme nous dfinissons les bords de dcalage lors de l'utilisation de la syntaxe quatre valeurs, l'ordre n'a pas d'importance : mask-position: top 2em left 1em et mask-position: left 1em top 2em produisent le mme rsultat.

La vritable puissance de la syntaxe quatre valeurs est qu'elle permet de dfinir des bords de dcalage autres que left et top. Par exemple, mask-position: bottom 10px right 20px cre un dcalage vertical de 10px vers le haut partir du bord infrieur et un dcalage horizontal de 20px vers la gauche partir du bord droit. Habituellement, la syntaxe quatre valeurs est utilise pour dcaler partir du bas et/ou de la droite. Mais cette syntaxe est galement utile si vous ne vous souvenez pas de l'ordre des bords de dcalage pour la syntaxe deux valeurs.

Une chose noter est que, contrairement aux valeurs de type <bg-position> pour background-position, les valeurs de type <position> pour mask-position ne permettent pas une syntaxe 3 valeurs et ne permettent pas de dcaler partir du center. Lors du dcalage du masque partir du bottom ou du right, le mask-position ncessite que les quatre valeurs soient dclares.

Pour que la syntaxe quatre valeurs soit valide, elle doit dfinir soit top soit bottom comme bord de dcalage vertical, avec la valeur de dcalage verticale en longueur ou en pourcentage, et soit left soit right comme bord de dcalage horizontal, avec la valeur de dcalage horizontale en longueur ou en pourcentage.

Dfinition formelle

Syntaxe formelle

mask-position = 
  <position>#  

<position> = 
  <position-one>   |
  <position-two>   |
  <position-four>  

<position-one> = 
  left                 |
  center               |
  right                |
  top                  |
  bottom               |
  x-start              |
  x-end                |
  y-start              |
  y-end                |
  block-start          |
  block-end            |
  inline-start         |
  inline-end           |
  <length-percentage>  

<position-two> = 
  [ left | center | right | x-start | x-end ] && [ top | center | bottom | y-start | y-end ]  |
  [ left | center | right | x-start | x-end | <length-percentage> ] [ top | center | bottom | y-start | y-end | <length-percentage> ]  |
  [ block-start | center | block-end ] && [ inline-start | center | inline-end ]  |
  [ start | center | end ]{2}                         

<position-four> = 
  [ [ left | right | x-start | x-end ] <length-percentage> ] && [ [ top | bottom | y-start | y-end ] <length-percentage> ]  |
  [ [ block-start | block-end ] <length-percentage> ] && [ [ inline-start | inline-end ] <length-percentage> ]  |
  [ [ start | end ] <length-percentage> ]{2}          

<length-percentage> = 
  <length>      |
  <percentage>  

Exemples

Utilisation simple

<section>
  <div></div>
</section>

section {
  border: 1px solid black;
  width: 250px;
  height: 250px;
}

div {
  width: 250px;
  height: 250px;
  margin-bottom: 10px;
  background: blue linear-gradient(red, blue);

  mask-image: url("/shared-assets/images/examples/mask-star.svg");
  mask-repeat: no-repeat;
  mask-position: top right;
}

Spcifications

Compatibilit des navigateurs

Voir aussi

• La proprit background-position
• La proprit mask-image
• La proprit mask-origin
• La proprit mask-repeat
• La proprit mask-size
• La proprit raccourcie mask
• La proprit mask-border
• La proprit mask-border-outset
• Introduction au masquage CSS
• Les proprits CSS mask
• Dclarer plusieurs masques
• Le module de masquage CSS
• La proprit background-position
• Le type de donne <position>