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

CSS-свойство mask-repeat CSS задаёт способ повторения изображений маски. Изображение маски может повторяться по горизонтальной или вертикальной оси, по обеим осям или не повторяться вовсе.

Синтаксис

/* One-value syntax */
mask-repeat: repeat-x;
mask-repeat: repeat-y;
mask-repeat: repeat;
mask-repeat: space;
mask-repeat: round;
mask-repeat: no-repeat;

/* Two-value syntax: horizontal | vertical */
mask-repeat: repeat space;
mask-repeat: repeat repeat;
mask-repeat: round space;
mask-repeat: no-repeat round;

/* Multiple values */
mask-repeat:
  space round,
  no-repeat;
mask-repeat:
  round repeat,
  space,
  repeat-x;

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

Значения

Свойство mask-repeat представляет собой список из двух значений <repeat-style>, разделённых запятыми: первое значение <repeat-style> задаёт повторение по горизонтали, а второе — по вертикали. Также можно указать одно ключевое слово, заменяющее два значения <repeat-style>.

Значения <repeat-style>

Значения <repeat-style>:

repeat

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

space

Изображение маски повторяется максимально возможное количество раз без обрезания. Если размер исходной области элемента как минимум вдвое превышает размер изображения маски в соответствующем измерении, свойство mask-position игнорируется, а первое и последнее изображения располагаются у краёв контейнера исходной области маски. Если размер блока исходной области маски не кратен размеру изображения маски, пустое пространство равномерно распределяется между повторяющимися изображениями маски.

Если размер блока исходной области меньше удвоенного размера изображения маски в заданном измерении, можно отобразить только одно изображение маски. В этом случае изображение располагается в соответствии со свойством mask-position, для которого по умолчанию задано значение 0% 0%. Изображение маски будет обрезано, только если оно больше блока исходной области маски.

round

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

no-repeat

Изображение маски не повторяется (поэтому область рисования маски не обязательно будет покрыта целиком). Положение неповторяющегося изображения маски задаётся CSS-свойством mask-position.

Сокращённые значения

Синтаксис с одним значением — это сокращённая форма полного синтаксиса с двумя значениями:

repeat-x

Эквивалент repeat no-repeat. Изображение повторяется по горизонтали столько раз, сколько необходимо, чтобы покрыть ширину области рисования маски. Изображения маски у левого и правого краёв (или у обоих краёв — в зависимости от значения mask-position) обрезаются, если ширина блока исходной области маски не кратна ширине изображения маски.

repeat-y

Эквивалент no-repeat repeat. Изображение повторяется по вертикали столько раз, сколько необходимо, чтобы покрыть высоту области рисования маски. Изображения маски у верхнего и нижнего краёв (или у обоих краёв — в зависимости от значения mask-position) обрезаются, если высота блока исходной области маски не кратна высоте изображения маски.

Описание

Свойство mask-repeat принимает пару значений, разделённых запятыми, или одно сокращённое значение. В синтаксисе с двумя значениями первое задаёт поведение повторения по горизонтали, а второе — по вертикали.

Несколько значений

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

Размеры и позиционирование

Значение свойства mask-repeat задаёт способ размещения изображений маски плиткой после того, как им заданы размеры и положение. Первое (и, возможно, единственное) повторение изображения маски располагается согласно свойству mask-position, для которого по умолчанию задано значение 0% 0% — верхний левый угол блока исходной области. Размер задаётся свойством mask-size, для которого по умолчанию задано значение auto. Положения повторяющихся масок рассчитываются относительно этого исходного экземпляра маски.

Обрезание

Изображения маски не повторяются, а обрезаются, если размер изображения маски превышает размер блока исходной области. Исключение — значение round: в этом случае единственная маска уменьшается до размеров блока исходной области.

При значениях repeat изображения маски могут обрезаться у края блока исходной области, если размер блока (ширина или высота) не кратен размеру маски.

Соотношение сторон

По умолчанию изображения маски сохраняют соотношение сторон, заданное свойством mask-size, либо исходное соотношение сторон, если для mask-size по умолчанию задано значение auto или оно указано явно. Соотношение сторон маски может измениться только в случае, когда в обоих направлениях задано значение round.

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

Округлённое количество повторений

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

Отрисованные размеры маски равны размеру блока исходной области, делённому на количество итераций масок в этом измерении; количество итераций — целое число больше нуля. Количество итераций вычисляется так: X' = D / round(D / X), где D — ширина или высота, а round() — функция, возвращающая ближайшее целое число больше нуля.

Например, если mask-repeat задано значение round, а mask-size устанавливает ширину маски равной 40px, то при ширине блока исходной области больше 0px, но меньше 60px, будет одна итерация, занимающая 100% ширины этого блока. Если ширина блока не меньше 60px, но меньше 100px, будет две итерации, каждая размером 50% от ширины блока. При ширине от 100px до 140px по горизонтальной оси поместятся три маски. Эти маски шириной «40px» будут иметь ширину 40px, только если размер блока исходной области кратен 40px.

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

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

mask-repeat = 
  <repeat-style>#

<repeat-style> = 
  repeat-x |
  repeat-y |
  [ repeat | space | round | no-repeat ]{1,2}

Примеры

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

В этом примере показано, как задать свойство mask-repeat для одной маски.

HTML

В нашем HTML используется простой элемент <div>:

<div></div>

CSS

Мы задаём 250px квадрат с градиентом от красного к синему и изображением маски в виде звезды размером 100px на 100px. Мы используем свойство mask-repeat, задавая round для горизонтального направления и space для вертикального.

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

  mask-image: url("/shared-assets/images/examples/mask-star.svg");
  mask-size: 100px 100px;

  mask-repeat: round space;
}

Результат

При значениях space и round изображение маски меньше блока исходной области и не обрезается. Значение round деформирует звезду, чтобы она не обрезалась и не оставляла пустого пространства, а значение space сохраняет соотношение сторон звезды, но при необходимости добавляет пространство между масками.

Округление количества повторений

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

<div></div>
<label
  >width: <span></span><br />
  <input type="range" min="0" max="400" value="250" id="width" />
</label>

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

  mask-image: url("/shared-assets/images/examples/mask-star.svg");
  mask-size: 100px 100px;

  mask-repeat: round space;
}
input {
  clear: both;
  width: 90%;
}

const div = document.querySelector("div");
const range = document.getElementById("width");
const output = document.querySelector("span");

range.addEventListener("change", () => {
  const value = `${range.value}px`;
  output.innerText = value;
  div.style.width = value;
});

Ширина маски задана как 100px. Если ширина блока исходной области составляет от 1px до 149px, отображается одна звезда; от 150px до 249px — две; от 250px до 349px — три и так далее.

Сокращённые значения

В этом примере показаны все сокращённые (однословные) значения mask-repeat.

HTML

Мы добавляем несколько элементов <section>, каждый из которых содержит <div> и имеет уникальное имя класса.

<section class="repeat">
  <div></div>
</section>
<section class="space">
  <div></div>
</section>
<section class="round">
  <div></div>
</section>
<section class="no-repeat">
  <div></div>
</section>
<section class="repeat-x">
  <div></div>
</section>
<section class="repeat-y">
  <div></div>
</section>

CSS

Для каждого <div> задаём одинаковые правила CSS, кроме значения mask-repeat, которое соответствует имени класса родительского элемента. Задаём размер маски и начальное положение mask-image в правом нижнем углу, поэтому обрезание будет происходить у верхних и левых масок — с их верхней и левой сторон.

div {
  width: 180px;
  height: 180px;
  background-image: linear-gradient(red, blue);

  mask-image: url("/shared-assets/images/examples/mask-star.svg");

  mask-size: 50px 50px;
  mask-position: bottom right;
}

.repeat div {
  mask-repeat: repeat;
}
.space div {
  mask-repeat: space;
}
.round div {
  mask-repeat: round;
}
.no-repeat div {
  mask-repeat: no-repeat;
}
.repeat-x div {
  mask-repeat: repeat-x;
}
.repeat-y div {
  mask-repeat: repeat-y;
}

Отображаем имя класса с помощью генерируемого содержимого.

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

Результат

Первая (а при значении no-repeat — единственная) звезда-маска имеет размер 50px на 50px и располагается в правом нижнем углу области рисования. Повторяющиеся звёзды размещаются выше и/или левее неё; обрезание происходит сверху и слева у самых верхних и левых звёзд. Обратите внимание: все звёзды имеют одинаковые размер и форму, кроме случая round, когда все маски уменьшились до 45px x 45px, чтобы вместить по четыре целые маски в каждом направлении. Если бы размер контейнера составлял 174px, в каждом направлении было бы по три звезды вместо четырёх, и каждая звезда растянулась бы.

Несколько изображений маски и способы их повторения

Для каждого изображения маски можно указать отдельное значение <repeat-style>, разделяя значения запятыми:

.extra-repeats {
  mask-image: url("mask1.png"), url("mask2.png");
  mask-repeat: repeat-x, repeat-y, space;
}

Каждому изображению соответствует свой стиль повторения. Поскольку значений mask-repeat больше, чем значений mask-image, лишние значения mask-repeat игнорируются.

.missing-repeats {
  mask-image:
    url("mask1.png"), url("mask2.png"), url("mask3.png"), url("mask4.png");
  mask-repeat: repeat-x, repeat-y;
}

Каждому изображению соответствует свой стиль повторения. Поскольку значений mask-image больше, чем значений mask-repeat, mask-repeat повторяется до тех пор, пока каждому mask-image не будет соответствовать значение mask-repeat. Здесь маски с нечётными номерами повторяются по оси x, а с чётными — по оси y.

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

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

См. также

• background-repeat
• mask-border-repeat
• Введение в маскирование CSS
• Свойства mask CSS
• Объявление нескольких масок
• модуль маскирования CSS