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 軸重複。