Свойство CSS `mask-position`

Свойство mask-position CSS задаёт начальное положение каждого изображения маски относительно слоя позиции маски, заданного свойством mask-origin.

Синтаксис

/* Single <position> keyword value */
/* Sets second value to 'center' */
mask-position: left;
mask-position: center;
mask-position: right;
mask-position: top;
mask-position: bottom;

/* Two <position> keyword values */
mask-position: left center;
mask-position: right top;

/* One length or percentage <position> value */
/* Horizontal position. Vertical position set to 'center' */
mask-position: 25%;
mask-position: 0px;
mask-position: 8em;

/* Two length or percentage <position> values */
/* First value: horizontal position. Second value: vertical position */
mask-position: 25% 75%;
mask-position: 0px 0px;
mask-position: 10% 8em;

/* Edge offsets: Four <position> values */
mask-position: bottom 10px right 20px;
mask-position: right 3em bottom 10px;
mask-position: bottom 10px right 0;

/* Multiple <position> values */
mask-position:
  top left,
  bottom 10px right 10px;
mask-position:
  1rem 1rem,
  center;

/* Global values */
mask-position: inherit;
mask-position: initial;
mask-position: revert;
mask-position: revert-layer;
mask-position: unset;

Значения

Это свойство задаётся списком значений, разделённых запятыми. Каждое значение имеет следующий тип:

position

Одно, два или четыре значения, задающих двумерное положение относительно краёв рамки элемента. Можно указывать относительные или абсолютные смещения.

Описание

Свойство mask-position определяет положение каждого слоя маски. К элементу может быть применено несколько слоёв маски. Число слоёв определяется количеством значений, разделённых запятыми, в значении свойства mask-image (даже значения none создают слой).

Каждое значение mask-position в списке значений, разделённых запятыми, сопоставляется с соответствующим слоем маски в порядке следования значений в списке mask-image. Если количество значений в двух свойствах различается:

• Если в mask-position указано больше значений, чем в mask-image, лишние значения mask-position не используются.
• Если в mask-position указано меньше значений, чем в mask-image, значения mask-position повторяются.

Каждое значение mask-position задаёт положение соответствующего слоя маски относительно соответствующего значения mask-origin. Значения свойства mask-origin аналогичным образом сопоставляются со значениями mask-image по порядку: лишние значения mask-position не используются, а значения mask-position повторяются, если их меньше, чем значений mask-origin. Таким образом, у каждого слоя маски есть соответствующие значения mask-origin и mask-position.

Если значение mask-origin не задано, по умолчанию используется padding-box, то есть началом координат каждого mask-position является внутренняя область элемента.

Синтаксис с одним значением

Если задано только одно значение mask-position, предполагается, что второе значение равно center. Если это значение — <length> или <percentage>, оно задаёт положение маски по горизонтальной оси, а маска при этом вертикально центрируется в исходной рамке. Например, mask-position: 0%; эквивалентно mask-position: 0% center.

Если для позиционирования используется одно ключевое слово, второе значение будет иметь значение center. По умолчанию mask-position равно 0% 0%, что эквивалентно mask-position: top left. Однако:

• mask-position: top; эквивалентно mask-position: top center;.
• mask-position: left; эквивалентно mask-position: center left.
• mask-position: center; равно mask-position: center center.

Если значение имеет тип <length>, оно задаёт горизонтальное положение как смещение от левого края области позиционирования маски. Положительное значение задаёт смещение внутрь от левого края рамки контейнера. Отрицательное значение позволяет расположить маску за пределами рамки элемента: оно задаёт смещение наружу, размещая изображение за левым краем контейнера.

Процентные значения

Значение типа <percentage> задаёт горизонтальное положение маски относительно ширины контейнера, отсчитывая его от левого края. Однако смещение отсчитывается не от края маски до края рамки. Вместо этого размер изображения маски вычитается из размера контейнера, а полученное значение умножается на процент, который используется как прямое смещение от левого края рамки. Это работает так же, как процентные значения для background-position.

Формула:

(container dimension - mask dimension) * position percentage = dimension offset value

Если ширина маски равна 100px, а ширина исходной рамки — 1000px, то значение mask-position: 10%; (эквивалент 10% 50%) расположит маску по центру по вертикали на расстоянии 90px от левого края. Формула: (1000 - 100) * 10% = 90. Если бы смещение слева равнялось 0%, левый край маски совпал бы с левым краем контейнера ((1000 - 100) * 0% = 0).

Если бы смещение слева равнялось 100%, правый край маски совпал бы с правым краем контейнера: левый край маски шириной 100px находился бы на расстоянии 900px ((1000 - 100) * 100% = 900) от левого края контейнера (ширина маски 100px плюс расстояние 900px от левого края дают 1000px от левого края — то есть положение правого края контейнера).

Синтаксис с двумя значениями

Значение <position> из двух частей задаёт положение изображения маски внутри области позиционирования маски. Значения длины и процента задают смещения от left и top этой области.

Если оба значения имеют тип <length> или <percentage>, либо являются ключевым словом center, первое значение задаёт горизонтальное положение как смещение от левого края области позиционирования маски, а второе — вертикальное положение как смещение от её верхнего края. Процентные значения смещения рассчитываются с учётом размера маски по соответствующему измерению.

Кроме того, если заданы значения типа <percentage>, первое значение также задаёт горизонтальное положение относительно левого края, а второе — вертикальное положение относительно верхнего края.

Порядок двух ключевых слов, специфичных для осей, можно менять; также можно менять местами ключевое слово, специфичное для оси, и значение длины или процента, но два значения длины или процента не взаимозаменяемы. Если одним из двух значений является top, right, bottom или left, порядок значений не имеет значения. Любое значение center или <length-percentage> в паре будет применено к другой координате.

Синтаксис с четырьмя значениями

Синтаксис с четырьмя значениями состоит из двух пар. Каждая пара содержит ключевое слово, указывающее край, от которого отсчитывается смещение, а также значение <length> и <percentage>, задающее расстояние смещения. Например, mask-position: left 1em top 2em задаёт горизонтальное смещение 1em от левого края рамки и вертикальное смещение 2em от верхнего края. Эквивалентная запись с двумя значениями: mask-position: 1em 2em.

При использовании синтаксиса с четырьмя значениями мы задаём края, от которых отсчитывается смещение, поэтому порядок не важен: mask-position: top 2em left 1em и mask-position: left 1em top 2em дают одинаковый результат.

Главное преимущество синтаксиса с четырьмя значениями — возможность задавать края смещения, отличные от left и top. Например, mask-position: bottom 10px right 20px задаёт вертикальное смещение 10px вверх от нижнего края и горизонтальное смещение 20px влево от правого края. Обычно синтаксис с четырьмя значениями используют для смещения от нижнего и/или правого края. Но он также полезен, если вы не помните порядок краёв смещения в синтаксисе с двумя значениями.

Следует отметить, что, в отличие от значений типа <bg-position> для свойства background-position, значения <position> для mask-position не допускают синтаксис с тремя значениями и не позволяют задавать смещение от center. Чтобы сместить маску относительно bottom или right, свойство mask-position требует указать все четыре значения.

Чтобы синтаксис с четырьмя значениями был корректным, необходимо указать top или bottom в качестве края вертикального смещения вместе со значением длины или процента для вертикального смещения, а также left или right в качестве края горизонтального смещения вместе со значением длины или процента для горизонтального смещения.

Формальное определение

Формальный синтаксис

mask-position = 
  <position>#

<position> = 
  [ [ left | center | right ] || [ top | center | bottom ] | [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ]? | [ [ left | right ] <length-percentage> ] && [ [ top | bottom ] <length-percentage> ] ]

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

Примеры

Основы использования

<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;
}

Спецификации

Совместимость с браузерами

См. также

• background-position
• mask-image
• mask-origin
• mask-repeat
• mask-size
• mask сокращённая запись
• mask-border
• mask-border-outset
• Введение в маскирование в CSS
• Свойства масок CSS mask
• Объявление нескольких масок
• Модуль маскирования в CSS
• background-position
• position