mask-repeat

Baseline 2023

新推出

自 ⁨2023 年 12 月⁩起，此功能可在最新的设备和浏览器版本上使用。此功能可能无法在较旧的设备或浏览器上使用。

mask-repeat 这个 CSS 属性设置了蒙版图像的重复方式。蒙版图像可以沿水平轴、垂直轴、双轴重复，或者完全不重复。

语法

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

蒙版图像不重复（因此蒙版绘制区域不一定会被完全覆盖）。不重复的蒙版图像的位置由 mask-position CSS 属性定义。

简写值

单值语法是完整的双值语法的简写：

单个值	等效的双值
`repeat-x`	`repeat no-repeat`
`repeat-y`	`no-repeat repeat`
`repeat`	`repeat repeat`
`space`	`space space`
`round`	`round round`
`no-repeat`	`no-repeat no-repeat`

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 宽。

正式定义

初始值	`repeat`
应用于	所有元素；在 SVG 中，它适用于除 `<defs>` 元素外的容器元素以及所有图形元素
继承性	否
计算值	由两个关键字组成，每个维度一个
动画类型	离散

正式语法

mask-repeat = 
  <repeat-style>#  

<repeat-style> = 
  repeat-x           |
  repeat-y           |
  <repetition>{1,2}  

<repetition> = 
  repeat     |
  space      |
  round      |
  no-repeat

示例

基本用法

此示例演示了如何为单个蒙版设置 mask-repeat 属性。

HTML

我们的 HTML 包含一个基本的 <div> 元素

html

<div></div>

CSS

我们定义了一个 250px 的正方形，背景是红色到蓝色的渐变，并使用一个 100px × 100px 的星星作为蒙版图像。我们使用 mask-repeat 属性，将水平方向设置为 round，垂直方向设置为 space。

css

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 则保持星星的宽高比，但在蒙版之间按需添加间距。

Round 迭代

使用相同的 HTML 和 CSS，这个演示包含一个滑块，可以改变容器的宽度，以展示在使用 round 时，蒙版会随着空间的允许而增大，直到可以容纳下一个迭代的蒙版；或者缩小，直到迭代次数不再能容纳。

<div></div>
<label
  >width: <output></output><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("output");

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>，且每个都有不同的类名。

html

<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 定位在右下角，这意味着任何裁剪都将发生在最上方和最左侧的蒙版的顶部和左侧。

css

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

我们使用生成内容来显示类名。

css

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 的情况外，所有的星星大小和形状都相同；在 round 的情况下，所有的蒙版都缩小到 45px × 45px，以便在每个方向上完整地容纳四个蒙版。如果容器是 174px，那么每个方向上将有三个星星，而不是四个，并且每个星星都会被拉伸。

多个蒙版图像和重复

你可以为每个蒙版图像指定不同的 <repeat-style>，用逗号分隔

css

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

每个图像都与相应的重复样式相匹配。由于 mask-repeat 值的数量多于 mask-image 值的数量，多余的 mask-repeat 值将被忽略。

css

.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 轴重复。