CSS-свойство `mask-size`

CSS-свойство mask-size задаёт размеры указанных изображений маски. Размеры изображения маски могут быть полностью или частично ограничены, чтобы сохранить их внутренние пропорции.

Синтаксис

/* Keyword syntax */
mask-size: cover;
mask-size: contain;
mask-size: auto;

/* One-value syntax */
/* Mask width. Sets height to 'auto'. */
mask-size: 50%;
mask-size: 3em;
mask-size: 12px;

/* Two-value syntax */
/* First value: mask width. Second value: mask height */
mask-size: 3em 25%;
mask-size: auto 6px;
mask-size: auto 50%;

/* Multiple values */
mask-size: auto, contain;
mask-size:
  50%,
  50% 25%,
  auto 25%;
mask-size: 6px, auto, contain;

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

Значения

Свойство mask-size принимает список значений <bg-size>, разделённых запятыми. Значение <bg-size> — это либо cover, либо contain, пара значений, задающих ширину и высоту (именно в таком порядке), либо одно значение, задающее ширину (в этом случае высота устанавливается в auto). Возможны следующие значения:

contain

Увеличивает или уменьшает изображение маски с сохранением пропорций, делая маску настолько большой, насколько это возможно в пределах контейнера, без обрезки или растяжения. Если изображение маски меньше контейнера, маска будет замощена, то есть повторена, если для свойства mask-repeat не задано значение no-repeat.

cover

Масштабирует изображение маски до наименьшего размера, необходимого для заполнения контейнера с сохранением пропорций. Если пропорции изображения маски отличаются от пропорций элемента, изображение будет обрезано по вертикали или горизонтали.

auto

Сохраняет исходные пропорции источника маски. Если задать это значение и для ширины, и для высоты, будет использоваться исходный размер ресурса маски. В противном случае значение auto масштабирует изображение маски в соответствующем направлении, сохраняя его исходные пропорции.

<length>

Отображает изображение маски с указанной длиной в соответствующем измерении (ширина, если значение задано первым или является единственным, высота — если оно указано вторым). Отрицательные значения недопустимы.

<percentage>

Отображает изображение маски в соответствующем измерении с размером, равным указанному проценту от области исходного блока, определяемой свойством mask-origin, значение которого по умолчанию — padding-box. Отрицательные значения недопустимы.

Описание

Свойство mask-size используется для задания размеров слоёв маски.

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

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

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

Каждое значение mask-size является значением <bg-size>. Есть три способа задать каждое <bg-size>: одно ключевое слово; две длины, процента или ключевое слово auto; либо одна длина, процент или auto:

• Доступные ключевые слова: cover и contain.
• Если указаны два значения, первое задаёт ширину маски, а второе — её высоту.
• Если указано одно значение, оно задаёт только ширину маски, а высота устанавливается в auto.

Значения ширины и высоты могут быть значением <length>, значением <percentage> или ключевым словом auto, которое используется по умолчанию. Если задать auto для одного или обоих значений, исходные пропорции изображения маски сохраняются.

Отображаемый размер изображения маски вычисляется следующим образом:

• Если заданы обе составляющие mask-size и ни одна из них не равна auto, изображение маски отображается в указанном размере.
• Если значение mask-size равно contain или cover, изображение отображается с сохранением пропорций в максимальном размере, который помещается в область позиционирования маски или заполняет её. Если у изображения нет внутренних пропорций, например в случае градиентов, оно отображается в размере области позиционирования маски.
• Если значение mask-size равно auto (что соответствует auto auto), изображение отображается в том размере, в котором маска отображалась бы без применения CSS, меняющего отображение; это её внутренний размер. Если у изображения нет внутренних размеров и внутренних пропорций, как в случае с градиентами CSS, оно отображается в размере области позиционирования маски, определяемой свойством mask-origin (значение по умолчанию — border-box). Если источник маски не имеет размеров, но имеет пропорции (соотношение сторон), значение auto отобразит его так, как если бы вместо него было задано contain. Если у изображения есть один внутренний размер и пропорции, оно отображается в размере, определяемом этим внутренним размером и пропорциями. Если у изображения есть один внутренний размер, но нет пропорций, оно отображается с использованием внутреннего размера и соответствующего измерения области позиционирования маски.
• Если mask-size содержит одну составляющую auto и одну составляющую, не являющуюся auto, что применимо ко всем значениям из одного элемента, пропорции сохраняются, если источник маски имеет внутренние пропорции. Если внутренних пропорций нет, предполагается, что значение auto соответствует размеру области позиционирования маски.

Как и для всех компонентов-свойств, входящих в сокращённое свойство, если задано сокращённое свойство mask, а значение свойства mask-size не указано ни в одном слое маски, для этих слоёв значение mask-size сбрасывается до начального значения auto.

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

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

mask-size = 
  <bg-size>#

<bg-size> = 
  [ <length-percentage [0,∞]> | auto ]{1,2} |
  cover |
  contain

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

Примеры

Задание размера маски в процентах

В этом примере показано базовое использование, а также продемонстрированы процентные значения для mask-size.

HTML

Мы добавили два элемента <div>:

<div class="width"></div>
<div class="height"></div>

CSS

Для элементов <div> заданы размеры, при которых высота вдвое больше ширины, а также градиентный фон и маска:

div {
  width: 200px;
  height: 400px;
  background: blue linear-gradient(red, blue);
  mask-image: url("/shared-assets/images/examples/mdn.svg");
}

Ширина маски одного элемента <div> задана как 50%, а для высоты используется значение по умолчанию auto. Высота маски второго элемента <div> задана как 50%, а ширина — как auto:

.width {
  mask-size: 50%;
}

.height {
  mask-size: auto 50%;
}

В случае width маска отображается шириной 100px (50% элемента шириной 200px). Для высоты используется значение по умолчанию auto, благодаря чему сохраняются пропорции маски. В случае height маска отображается высотой 200px (50% контейнера высотой 400px). Ширина явно задана как auto, благодаря чему сохраняются пропорции маски.

body {
  display: flex;
  gap: 20px;
}

Результат

Cover и contain

В этом примере показаны ключевые слова для mask-size.

HTML

Заданы три элемента <section>, каждый с отдельным именем класса и содержащий элемент <div>.

<section class="auto">
  <div></div>
</section>
<section class="cover">
  <div></div>
</section>
<section class="contain">
  <div></div>
</section>

CSS

Для элементов <div> заданы размеры, при которых высота вдвое больше ширины, а также градиентный фон и маска:

div {
  width: 200px;
  height: 400px;
  background: blue linear-gradient(red, blue);
  mask-image: url("/shared-assets/images/examples/mask-star.svg");
}

Для mask-size двух элементов <div> заданы ключевые значения свойства. Для третьего элемента <div> задано значение mask-size — auto, демонстрирующее исходные внутренние размеры маски:

.auto div {
  mask-size: auto;
}

.cover div {
  mask-size: cover;
}

.contain div {
  mask-size: contain;
}

Значения свойств отображаются с помощью генерируемого содержимого.

section::before {
  content: "mask-size: " attr(class) ";";
  display: block;
  text-align: center;
  border-bottom: 1px solid;
}

body {
  display: flex;
  flex-flow: row wrap;
  gap: 10px;
}
section {
  border: 1px solid;
}

Результат

При значении auto звезда отображается в своём внутреннем размере 100px на 100px. При значении cover звезда увеличивается до высоты 400px, заполняя весь исходный блок. При значении contain звезда увеличивается, пока один из её размеров не сравняется с соответствующим размером исходного блока. Это означает, что звезда становится максимально большой (шириной 200px), но всё ещё помещается в нём.

Если маска больше контейнера

В этом примере, использующем те же HTML и CSS, что и выше, но с другим размером исходного блока, рассматривается ситуация, когда исходный блок меньше внутренних размеров маски.

<section class="auto">
  <div></div>
</section>
<section class="cover">
  <div></div>
</section>
<section class="contain">
  <div></div>
</section>

div {
  background: blue linear-gradient(red, blue);
  mask-image: url("/shared-assets/images/examples/mask-star.svg");
}

.auto div {
  mask-size: auto;
}

.cover div {
  mask-size: cover;
}

.contain div {
  mask-size: contain;
}

section::before {
  content: attr(class);
  display: block;
  text-align: center;
  border-bottom: 1px solid;
}

body {
  display: flex;
  flex-flow: row wrap;
  gap: 10px;
}
section {
  border: 1px solid;
}

Отличается только размер контейнера (и генерируемого содержимого):

div {
  width: 70px;
  height: 70px;
}

Значение contain вписывает маску в исходный блок. Значение cover заполняет его. В обоих случаях маска уменьшается с сохранением исходных пропорций. При значении auto маска обрезается, поскольку её внутренние размеры больше размеров блока.

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

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

См. также

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