CSS 遮罩屬性

CSS 遮罩是一種技術，透過應用一個遮罩，根據所應用的遮罩影像的 alpha 通道（以及可選的顏色）選擇性地顯示或隱藏元素的部分，從而定義元素的可見部分。

遮罩入門指南介紹了不同型別的遮罩影像及其模式。關於宣告多個遮罩的指南討論了遮罩層和 mask 簡寫屬性，簡要介紹了簡寫屬性的各個分量屬性。在本指南中，我們將更詳細地探討這些分量屬性，並看看它們如何相互作用。我們還將解釋，在聲明瞭多個遮罩影像的情況下，遮罩層是如何合成或組合的。

CSS 遮罩由一個或多個遮罩層組成，對於以逗號分隔的 mask 或 mask-image 值列表中的每個值，都會建立一個遮罩層，無論這些值是影像、遮罩源還是關鍵字 none。每個 mask-image 都相對於一個原點框進行定位。遮罩影像可以被調整大小、重複和裁剪，然後與前面的圖層合成在一起，以在元素上建立最終的視覺遮罩。

`mask-image` 屬性

建立遮罩的最低要求是將 mask-image 屬性設定為 none 以外的值。在遮罩源列表中的關鍵字 none 會建立一個遮罩層。但是，如果 none 是 mask-image 屬性的唯一值，則不會發生遮罩。

遮罩影像可以是 CSS 漸變、匯入的影像（如 PNG、SVG 等），或 SVG <mask> 元素。

在這個例子中，我們建立了五個遮罩層，包括一個匯入的影像、兩個漸變、一個沒有影像的層，以及一個 SVG <mask> 源作為遮罩影像。

css

.masked-element {
  mask-image:
    url("alphaImage.png"), linear-gradient(to right, black, transparent),
    radial-gradient(circle, white 50%, transparent 75%), none, url("#svg-mask");
}

因為其中一個遮罩影像被指定為 none，所以只有四個遮罩影像應用於 .masked-element 元素，但建立了五個遮罩層。

`none` 的重要性

none 層通常沒有視覺效果（參見 mask-composite 屬性瞭解它如何影響應用的遮罩），但由於以逗號分隔的 mask-* 值列表中的每個值都應用於一個單獨的遮罩層，因此即使它不改變合成的遮罩，none 值也起著重要作用。

在我們五層結構中的第四層將匹配任何其他以逗號分隔的 mask-* 屬性值中的第四個值。如前所述，層的數量由 mask-image 屬性值中以逗號分隔的值的數量決定，即使某個值為 none。每個 mask-* 的值都按順序與 mask-image 的值匹配。如果 mask-* 屬性中的值的數量與遮罩層的數量不同，任何多餘的值都將被忽略，或者，如果屬性的值少於遮罩層的數量，這些值將被重複。

如果一個 mask-* 屬性只有一個值，這個值將應用於所有的層。如果我們有五個值，第四個值將應用於 none 層，最後一個值將應用於 <mask> 源層。如果有兩個以逗號分隔的值，第一個值將僅應用於所有奇數層，包括那個 <mask> 源層。例如，每個 mask-* 屬性可以有不同數量的值。

css

.masked-element {
  mask-image:
    url("alphaImage.png"), linear-gradient(to right, black, transparent),
    radial-gradient(circle, white 50%, transparent 75%), none, url("#svg-mask");
  mask-repeat: repeat-x, repeat-y;
  mask-position:
    center,
    top left,
    bottom right;
}

在這種情況下，每個奇數層將在 x 軸上重複，而每個偶數層將在 y 軸上重複。第一和第四層影像將居中，而第二和第五層將位於左上角。none 意味著第五層的 #svg-mask 影像將從左上角開始沿 x 軸重複。

瞭解更多關於遮罩層和 none 關鍵字的資訊。

`mask-mode` 屬性

mask-mode 屬性可以用來將每個遮罩層的模式設定為 alpha 或 luminance，或者透過將值設定為 match-source（預設值）來使其預設為源的模式。雖然大多數 mask-* 屬性都有一個類似的 background-* 屬性（例如，mask-image 類似於 background-image 屬性），但 mask-mode 和 mask-composite 沒有類似的 background 屬性。

遮罩型別：`alpha` 和 `luminance`

每個遮罩要麼是 alpha 遮罩，要麼是 luminance 遮罩。

對於 alpha 遮罩，每個遮罩畫素的 alpha 透明度很重要。遮罩不透明的地方，元素的相應部分將是可見的。遮罩透明的地方，元素的相應部分將被隱藏。遮罩半透明的地方，元素也將同樣半透明。遮罩的顏色不重要，只有顏色的 alpha 透明度重要。

對於 luminance 遮罩，遮罩顏色的亮度和 alpha 通道都決定了被遮罩區域的不透明度。

注意：後續所有示例都使用以下影像作為元素的 background-image，我們將對該元素應用遮罩。

這個例子演示了 alpha 和 luminance 遮罩之間的區別。遮罩是相同的，但在 alpha 遮罩中，只有漸變遮罩顏色的 alpha 透明度重要。在 luminance 示例中，R、G、B 和 A 都很重要。

兩個容器包含影像，最後一個是空的，但包含在內以顯示我們將用作 mask-image 的漸變。

html

<div class="alpha">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>
<div class="luminance">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>
<div class="gradient"></div>

body {
  display: flex;
  gap: 20px;
  padding: 15px;
  background-image: conic-gradient(
    transparent 90deg,
    rgb(0 0 0 / 0.05) 90deg 180deg,
    transparent 180deg 270deg,
    rgb(0 0 0 / 0.05) 270deg
  );
  background-size: 30px 30px;
}
div,
svg,
img {
  width: 220px;
  aspect-ratio: 1;
}
div {
  border: 1px solid black;
}

我們聲明瞭一個帶有紅色、透明和半透明紅色對角條紋的 repeating-linear-gradient。這個漸變被用作我們的遮罩，並且對於最後一個容器，用作背景影像。

css

img {
  mask-image: repeating-linear-gradient(
    to bottom right,
    red 0 20px,
    #ff000055 20px 40px,
    transparent 40px 60px
  );
}
.gradient {
  background: repeating-linear-gradient(
    to bottom right,
    red 0 20px,
    #ff000055 20px 40px,
    transparent 40px 60px
  );
}

我們為每個影像設定了不同的 mask-mode 屬性值。

css

.alpha img {
  mask-mode: alpha;
}

.luminance img {
  mask-mode: luminance;
}

在 alpha 情況下，只有漸變顏色的透明度重要。漸變為不透明紅色的地方，影像就不透明。漸變為透明的地方，影像就被隱藏。漸變為 50% 不透明的地方，影像就 50% 不透明。在 luminance 情況下，顏色的亮度很重要！請參閱Alpha 透明度與亮度來了解使用顏色 R、G、B 和 A 通道確定遮罩不透明度的方程式。

`mask-mode` 的預設值：`match-source`

mask-mode 屬性的預設值是 match-source。這個值會將 mask-mode 設定為與遮罩的模式型別相匹配。除了遮罩源是 SVG <mask> 元素的情況外，match-source 值會解析為 alpha。

當使用 SVG <mask> 元素作為遮罩源時，match-source 值會解析為 <mask> 元素的 mask-type 屬性的值。如果 <mask> 元素（而不是“被遮罩的元素”）沒有定義 CSS mask-type 屬性，該屬性將預設為 SVG mask-type 屬性的值（如果存在）。如果該屬性也被省略，match-source 值將解析為 luminance。

繼續 masked-element 示例，如果我們沒有明確設定 mask-mode 屬性，它將對每個層預設為 match-source，就好像我們設定了以下內容：

css

.masked-element {
  mask-image:
    url("alphaImage.png"), linear-gradient(to right, black, transparent),
    radial-gradient(circle, white 50%, transparent 75%), none, url("#svg-mask");
  mask-mode: match-source;
}

或者，使用 mask 簡寫：

css

.masked-element {
  mask:
    url("alphaImage.png") match-source,
    linear-gradient(to right, black, transparent) match-source,
    radial-gradient(circle, white 50%, transparent 75%) match-source,
    none match-source,
    url("#svg-mask") match-source;
}

第一個遮罩層 url("alphaImage.png") 引用了一個影像。由於這不是 <svg> 中的 <mask> 元素，mask-mode 解析為 alpha，該影像的不透明部分使元素的相應部分可見，而透明或半透明部分則不可見或部分可見。

linear-gradient(to right, black, transparent) 是第二個遮罩層，radial-gradient(circle, white 50%, transparent 75%) 是第三個。同樣，這些不是 <mask> 元素，所以 match-source 值解析為 alpha。這些層的遮罩效果預設由漸變遮罩的不透明度決定。

第四個遮罩層聲明瞭 none，這意味著該層的遮罩是透明黑色。.masked-element 類設定了 mask-mode: match-source;。如果 mask-mode 是一個包含五個不同值的逗號分隔列表，第四個值將應用於這個 none 層，從而允許第五個值應用於第五層。

第五個遮罩層由一個 SVG <mask> 元素組成，其 id 為 svg-mask。雖然其他層的預設遮罩模式是 alpha，但 SVG <mask> 元素的預設遮罩型別是 mask-type 的值，或者如果未設定，則是 mask-type 屬性。如果該屬性也未定義，則該值預設為 luminance。換句話說，<mask> 的遮罩效果由 <mask> 元素顏色的亮度和透明度共同決定。

如果我們根本不宣告 mask-mode 屬性，並讓它對每個遮罩層預設為 match-source，那麼在這個 .masked-element 案例中，結果將解析為：

css

.masked-element {
  mask-image:
    url("alphaImage.png"), linear-gradient(to right, black, transparent),
    radial-gradient(circle, white 50%, transparent 75%), none, url("#svg-mask");
  mask-mode: alpha, alpha, alpha, match-source, luminance;
}

或者，使用 mask 簡寫：

css

.masked-element {
  mask:
    url("alphaImage.png") alpha,
    linear-gradient(to right, black, transparent) alpha,
    radial-gradient(circle, white 50%, transparent 75%) alpha,
    none match-source,
    url("#svg-mask") luminance;
}

`mask-position` 屬性

類似於 background-position 屬性，mask-position 屬性設定遮罩影像相對於遮罩層原點框的初始位置，該原點框由 mask-origin 屬性定義。其語法遵循 background-position 的 <position> 語法，值為一個、兩個或四個 <position> 值，定義一到兩個相對或絕對位置偏移。

單值語法

如果只指定一個關鍵字值，該值指定遮罩將放置的遮罩原點邊緣，另一個維度為 center。

如果只指定一個 <length-percentage> 值，這指定了相對於遮罩原點左邊緣的 X 座標，Y 座標設定為 50%。

如果指定了兩個關鍵字值，值的順序不重要，但值不能包含兩個垂直或兩個水平軸的值；left right 和 top bottom 都是無效的。

雙值語法

如果存在兩個值，包括一個關鍵字和一個 <length-percentage> 值，順序僅在關鍵字是 center 時才重要。

如果關鍵字是 left 或 right，它定義了相對於左邊緣的 X 座標，另一個值定義了相對於上邊緣的 Y 座標。
類似地，top 或 bottom 關鍵字定義了將元素分別定位在上邊緣或下邊緣的 Y 座標，另一個值定義了相對於遮罩原點框左邊緣的 X 值。
當一個值是 center 關鍵字，另一個是 <length-percentage> 時，第一個值定義水平位置，第二個值定義垂直位置。

如果存在兩個值且都是 <length-percentage> 值，順序再次重要；第一個值定義了相對於遮罩定位區域左邊緣偏移的水平位置，而第二個值定義了相對於遮罩定位區域上邊緣偏移的垂直位置。

四值語法

遮罩位置也可以相對於除左上角以外的角。四值語法允許從任何角偏移遮罩。該值包括兩個 <length-percentage> 偏移量，每個偏移量前面都有該偏移量的原點邊。先宣告水平對還是垂直對並不重要，但你必須在每對中的偏移量 <length-percentage> 之前宣告原點邊關鍵字（left、right、top、bottom、x-start、x-end、y-start、y-end、block-start、block-end、inline-start 或 inline-end），並且兩個原點邊不能來自同一軸。

在兩個 <length-percentage> 的語法中，原點邊按順序是 top 和 left。例如，mask-position: 10px 20px 等同於 mask-position: left 10px top 20px。當從頂部和左側偏移時，不需要指定偏移邊，但順序很重要。使用四值語法，你可以使用 mask-position 從任何邊的組合來偏移遮罩影像，例如 left 10px bottom 20px，並且邊的順序不重要，因為偏移邊由其前面的關鍵字而不是宣告順序來定義。

百分比值

當使用百分比值進行偏移時，遮罩的尺寸會從元素的尺寸中減去，就像使用 background-position 的百分比偏移一樣。

定位重複的遮罩影像

mask-position 屬性定義了遮罩影像的初始位置。所謂“初始位置”，如果遮罩重複，瀏覽器會將第一個遮罩影像放置在 mask-position 屬性定義的位置，從而定義遮罩重複的佈局。

在這個例子中，我們將第一張影像的位置設定為 bottom right，這意味著第一個遮罩將被放置在遮罩原點框的右下邊緣。因為遮罩影像預設是重複的，所以重複的遮罩將相對於第一個放置的遮罩的頂部和左側進行定位。

<div class="keywords">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>
<div class="twoValue">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>
<div class="fourValue">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>

div,
img {
  width: calc(30vw - 20px);
}

css

img {
  mask-image: url("https://mdn.github.io/shared-assets/images/examples/mask-star.svg");
}
.keywords img {
  mask-position: bottom right;
}
.twoValue img {
  mask-position: -20px -10px;
}
.fourValue img {
  mask-position: right -20px bottom -10px;
}

div::before {
  content: 'class="' attr(class) '"';
  display: block;
  text-align: center;
  font-family: monospace;
}
body {
  flex-flow: row wrap;
}

mask-position 定義了第一個遮罩影像的放置位置。這個演示展示了第一個影像被放置在哪裡：

img {
  mask-repeat: no-repeat;
}

因為 mask-repeat 屬性的預設值是 repeat，所以影像會根據第一個遮罩的位置沿 X 和 Y 軸重複。

雙值示例定義了原始遮罩的頂部和左側偏移。四值示例結合了前面兩個示例，使用與第二個影像相同的偏移量來定位第一個遮罩，但從第一個影像中演示的相同邊緣開始。

在第一張圖片中，首先被放置的星星是右下角的那顆，重複的星星在它的上方和左側。由於這種定位，初始的星星沒有被裁剪，但最頂部和最左側的星星被裁剪了。

如果我們沒有明確設定 mask-position 屬性，它將對每個層預設為 0% 0%，即遮罩的左上角與遮罩原點框的左上角對齊。繼續 masked-element 示例，就好像我們設定了以下內容：

css

.masked-element {
  mask-image:
    url("alphaImage.png"), linear-gradient(to right, black, transparent),
    radial-gradient(circle, white 50%, transparent 75%), none, url("#svg-mask");
  mask-mode: match-source;
  mask-position: 0% 0%;
}

或者，使用 mask 簡寫來擴充套件示例：

css

.masked-element {
  mask:
    url("alphaImage.png") 0% 0% match-source,
    linear-gradient(to right, black, transparent) 0% 0% match-source,
    radial-gradient(circle, white 50%, transparent 75%) 0% 0% match-source,
    none 0% 0% match-source,
    url("#svg-mask") 0% 0% match-source;
}

`mask-origin` 屬性

當一個元素有內邊距、邊框或兩者都有時，mask-origin 屬性定義了這些框邊緣值中的哪一個作為遮罩原點框，即遮罩定位區域，遮罩影像在該層內被定位。mask-origin 屬性類似於 background-origin 屬性，但具有不同的初始值和僅適用於 SVG 的值。

HTML 元素的遮罩可以包含在其內容邊框框、內邊距框或內容框內。例如，如果 mask-position 是 top left，那是相對於邊框的外邊緣、內邊距的外邊緣還是內容的外邊緣？

在mask-position 遮罩示例中，定義的位置是相對於邊框盒（預設行為），儘管值得注意的是，<img> 沒有設定邊框或內邊距，因此在這種情況下，內容盒、內邊距盒和邊框盒的原點都是相同的。

<div class="border-box">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>
<fieldset>
  <legend>Set the <code>mask-origin</code> value</legend>
  <label
    ><input type="radio" name="origin" id="origin_border-box" checked />
    border-box</label
  >
  <label
    ><input type="radio" name="origin" id="origin_padding-box" />
    padding-box</label
  >
  <label
    ><input type="radio" name="origin" id="origin_content-box" />
    content-box</label
  >
</fieldset>

div {
  all: unset;
}
legend {
  align-self: baseline;
}
label {
  display: block;
}

在這個例子中，mask-position 將初始遮罩放置在具有大邊框和內邊距的 <img> 元素的左上角，並帶有綠色背景色，以便能夠在內邊距區域看到星星遮罩。

css

img {
  mask-image: url("https://mdn.github.io/shared-assets/images/examples/mask-star.svg");
  mask-position: top left;
  padding: 15px;
  border: 15px solid;
  background-color: green;
}
:has(#origin_border-box:checked) img {
  mask-origin: border-box;
}
:has(#origin_padding-box:checked) img {
  mask-origin: padding-box;
}
:has(#origin_content-box:checked) img {
  mask-origin: content-box;
}

透過更改所選的單選按鈕來更改 mask-origin 屬性的值，並在這樣做時觀察左上角星星遮罩的位置。

預設值是 border-box。使用這個值，初始遮罩被放置在邊框的左上邊緣並且不會被裁剪。當初始遮罩被放置在內邊距的外部或內部邊緣時，它的上方和左側有空間；這些重複的遮罩會被裁剪。

繼續 masked-element 示例，如果我們沒有明確設定 mask-origin 屬性，它將對每個層預設為 border-box，就好像我們設定了以下內容：

css

.masked-element {
  mask-image:
    url("alphaImage.png"), linear-gradient(to right, black, transparent),
    radial-gradient(circle, white 50%, transparent 75%), none, url("#svg-mask");
  mask-mode: match-source;
  mask-position: 0% 0%;
  mask-origin: border-box;
}

或者，使用 mask 簡寫來擴充套件示例：

css

.masked-element {
  mask:
    url("alphaImage.png") 0% 0% border-box match-source,
    linear-gradient(to right, black, transparent) 0% 0% border-box match-source,
    radial-gradient(circle, white 50%, transparent 75%) 0% 0% border-box
      match-source,
    none 0% 0% border-box match-source,
    url("#svg-mask") 0% 0% border-box match-source;
}

對於沒有相關 CSS 佈局框的 SVG 元素，遮罩可以包含在 SVG 元素的填充、描邊或視口框內。

`mask-clip` 屬性

mask-clip 屬性決定了元素中受遮罩影響的區域，有效地在定義的框邊緣處裁剪元素。它類似於 background-clip 屬性，但有一些不同的值。

因為 mask-clip 屬性接受所有 mask-origin 的值，並且兩者都有相同的 border-box 預設值，所以這兩個屬性可能看起來很相似，但它們的用途非常不同。mask-origin 決定了遮罩影像將被放置在哪裡，而 mask-clip 屬性則導致原始元素的內容被裁剪到指定的框。理解它們兩者都很重要：如果 mask-origin 導致 mask-position 將遮罩影像放置在裁剪區域之外，那麼遮罩將被裁剪。

mask-clip 屬性接受所有 mask-origin 的值，以及它自己的 no-clip 值。no-clip 值設定繪製的內容不被裁剪。你仍然可以透過使用小於零或解析為大於 100% 的 mask-position 值將遮罩影像定位在邊框內容區域之外來使其被裁剪。

將 mask-clip 和 mask-origin 設定為不同的值可能會導致遮罩層影像被裁剪。例如，如果一個帶有邊框和內邊距的元素將 mask-clip 設定為 content-box，mask-origin 設定為 border-box，並且 mask-position 設定為 top left 邊緣，那麼遮罩層影像將在左上邊緣被裁剪。

下一個示例在前一個示例中添加了裁剪選項，以演示不同的非 SVG mask-clip 值，並展示它們如何影響不同的 mask-origin 值。

<div class="border-box">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>
<fieldset>
  <legend>Set the <code>mask-clip</code> value</legend>
  <label
    ><input type="radio" name="clip" id="clip_border-box" checked />
    border-box</label
  >
  <label
    ><input type="radio" name="clip" id="clip_padding-box" /> padding-box</label
  >
  <label
    ><input type="radio" name="clip" id="clip_content-box" /> content-box</label
  >

  <label><input type="radio" name="clip" id="clip_no-clip" /> no-clip</label>
</fieldset>
<fieldset>
  <legend>Set the <code>mask-origin</code> value</legend>
  <label
    ><input type="radio" name="origin" id="origin_border-box" checked />
    border-box</label
  >
  <label
    ><input type="radio" name="origin" id="origin_padding-box" />
    padding-box</label
  >
  <label
    ><input type="radio" name="origin" id="origin_content-box" />
    content-box</label
  >
</fieldset>

css

:has(#clip_border-box:checked) img {
  mask-clip: border-box;
}
:has(#clip_padding-box:checked) img {
  mask-clip: padding-box;
}
:has(#clip_content-box:checked) img {
  mask-clip: content-box;
}

第一個遮罩被放置在遮罩原點容器的左上邊緣，然後重複。如果原點框是 border-box 而裁剪區域是 content-box，那麼遮罩原點容器的頂部和左側區域將被裁剪。通常，你會希望 mask-clip 與 mask-origin 相同。

繼續 masked-element 示例，如果我們沒有明確設定 mask-clip 屬性，它將對每個層預設為 border-box，就好像我們設定了以下內容：

css

.masked-element {
  mask-image:
    url("alphaImage.png"), linear-gradient(to right, black, transparent),
    radial-gradient(circle, white 50%, transparent 75%), none, url("#svg-mask");
  mask-mode: match-source;
  mask-position: 0% 0%;
  mask-origin: border-box;
  mask-clip: border-box;
}

或者，使用 mask 簡寫來擴充套件示例：

css

.masked-element {
  mask:
    url("alphaImage.png") 0% 0% border-box border-box match-source,
    linear-gradient(to right, black, transparent) 0% 0% border-box border-box
      match-source,
    radial-gradient(circle, white 50%, transparent 75%) 0% 0% border-box
      border-box match-source,
    none 0% 0% border-box border-box match-source,
    url("#svg-mask") 0% 0% border-box border-box match-source;
}

在 mask 簡寫中，如果只給出一個 <geometry-box> 值，它會同時設定 mask-origin 和 mask-clip 屬性值。如果存在兩個 <geometry-box> 值，第一個定義 mask-origin，第二個定義 mask-clip。

對於不引用 SVG <mask> 元素的遮罩層影像，mask-clip 屬性定義了遮罩繪製區域，即受遮罩影響的區域，是邊框、內邊距還是內容框。元素的繪製內容將被限制在該區域內。

當遮罩層的 mask-image 源是 <mask> 時，mask-clip 屬性沒有效果。相反，<mask> 元素的 x、y、width、height 和 maskUnits 屬性決定了遮罩繪製區域。

`mask-size` 屬性

mask-size 屬性用於調整遮罩層的大小。此屬性類似於 background-size 屬性，接受相同的值。調整遮罩大小時，請記住元素中未被遮罩影像覆蓋的區域是隱藏的。

有三種方式可以宣告 mask-size：

cover 或 contain 關鍵字，
一個長度、百分比或關鍵字 auto，或
兩個值的組合，可以是長度、百分比和關鍵字 auto。

遮罩影像可以保持其自然大小、被拉伸或被約束以適應可用空間。遮罩影像的寬高比預設保持不變，但宣告兩個 <length-percentage> 值可能會扭曲遮罩影像，如果這兩個值的比例與原始影像不同（mask-repeat: round 是另一個可能扭曲遮罩影像的屬性/值對）。

如果 mask-size 設定為 contain，遮罩影像將是其在完全包含在遮罩定位區域內所能達到的最大尺寸。在這種情況下，遮罩影像不會被裁剪，而是被完全包含。

當設定為 cover 時，遮罩影像將是其完全覆蓋整個遮罩定位區域所能達到的最小尺寸，如果遮罩的寬高比與遮罩定位區域的寬高比不同，遮罩將被裁剪。

換句話說，使用 cover 和 contain，遮罩的至少一個維度將與遮罩定位區域的相同維度大小相同；遮罩影像會放大或縮小，使得其寬度與遮罩定位區域的寬度相同，或者遮罩影像的高度等於遮罩定位區域的高度。

使用 cover、contain 和 <percentage> 值時，大小是相對於原點框的。在我們的星星遮罩和旗幟影像示例中，遮罩影像和 <img> 的寬高比都是 1:1，這意味著在這種情況下，cover、contain 和 100% 都會產生相同大小的遮罩。這個例子演示了當 mask-size 設定為 cover、contain 或 <percentage> 值時，遮罩的實際大小可能會根據 mask-origin 屬性的值而有所不同。

<div class="border-box">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>
<fieldset>
  <legend>Set the <code>mask-origin</code> value</legend>
  <label
    ><input type="radio" name="origin" id="border-box" checked />
    border-box</label
  >
  <label
    ><input type="radio" name="origin" id="padding-box" /> padding-box</label
  >
  <label
    ><input type="radio" name="origin" id="content-box" /> content-box</label
  >
</fieldset>

img {
  mask-image: url("https://mdn.github.io/shared-assets/images/examples/mask-star.svg");
  mask-position: top left;
  padding: 15px;
  border: 15px solid;
  background-color: green;
}

css

img {
  mask-size: 100%;
}
:has(#border-box:checked) img {
  mask-origin: border-box;
}
:has(#padding-box:checked) img {
  mask-origin: padding-box;
}
:has(#content-box:checked) img {
  mask-origin: content-box;
}

更改 mask-origin 屬性的值，看看不同的值如何影響遮罩的大小。

這個例子包含了一個 <percentage> 值。當指定一個 <length-percentage> 值時，它只定義遮罩的寬度，高度預設為 auto，這會保持寬高比。當指定兩個值時，第一個定義遮罩的寬度，第二個定義其高度。

mask-size 的預設值是 auto，這會以其固有尺寸渲染遮罩，即如果沒有應用 CSS，遮罩將顯示的尺寸。如果你設定單個 <length-percentage> 值，或者兩個值的比例與寬高比相同，則會保持遮罩影像的底層寬高比。如果你宣告的兩個值的比例與寬高比不同，遮罩影像會被扭曲。

與簡寫屬性的所有普通分量屬性一樣，如果設定了 mask 簡寫屬性，並且在任何遮罩層中沒有定義 mask-size 屬性的值，那麼 mask-size 的值將為這些遮罩層重置為其初始值 auto。

如果影像沒有固有比例，例如 CSS 漸變，預設的 auto 是由 mask-origin 屬性設定的整個遮罩定位區域。

繼續 masked-element 示例，如果我們沒有明確設定 mask-size 屬性，它將對每個層預設為 auto，就好像我們設定了以下內容：

css

.masked-element {
  mask-image:
    url("alphaImage.png"), linear-gradient(to right, black, transparent),
    radial-gradient(circle, white 50%, transparent 75%), none, url("#svg-mask");
  mask-mode: match-source;
  mask-position: 0% 0%;
  mask-origin: border-box;
  mask-clip: border-box;
  mask-size: auto;
}

或者，使用 mask 簡寫來擴充套件示例，mask-size 分量跟在 mask-position 值之後，用正斜槓 (/) 分隔：

css

.masked-element {
  mask:
    url("alphaImage.png") 0% 0% / auto border-box border-box match-source,
    linear-gradient(to right, black, transparent) 0% 0% / auto border-box
      border-box match-source,
    radial-gradient(circle, white 50%, transparent 75%) 0% 0% / auto border-box
      border-box match-source,
    none 0% 0% / auto border-box border-box match-source,
    url("#svg-mask") 0% 0% / auto border-box border-box match-source;
}

`mask-repeat` 屬性

mask-repeat 屬性定義了在初始遮罩影像被調整大小和定位後，遮罩影像如何重複或平鋪。mask-repeat 屬性定義了該遮罩影像是否以及如何沿水平和垂直軸重複。在之前的大多數示例中，你可能已經注意到星星遮罩沿 X 和 Y 軸重複。這是因為 repeat 是預設值。

mask-repeat 屬性類似於 background-repeat 屬性，接受相同的 <repeat-style> 值。與 background-repeat 的情況一樣，第一個（也可能是唯一的）遮罩影像重複由 *-position 屬性定位，並由 *-size 屬性調整大小。重複的背景或遮罩影像的位置是基於這個初始影像例項的。

繼續 masked-element 示例，如果我們沒有明確設定 mask-repeat 屬性，它將對每個層預設為 repeat，就好像我們設定了以下內容：

css

.masked-element {
  mask-image:
    url("alphaImage.png"), linear-gradient(to right, black, transparent),
    radial-gradient(circle, white 50%, transparent 75%), none, url("#svg-mask");
  mask-mode: match-source;
  mask-position: 0% 0%;
  mask-origin: border-box;
  mask-clip: border-box;
  mask-size: auto;
  mask-repeat: repeat;
}

或者，使用 mask 簡寫來擴充套件示例：

css

.masked-element {
  mask:
    url("alphaImage.png") 0% 0% / auto repeat border-box border-box match-source,
    linear-gradient(to right, black, transparent) 0% 0% / auto repeat border-box
      border-box match-source,
    radial-gradient(circle, white 50%, transparent 75%) 0% 0% / auto repeat
      border-box border-box match-source,
    none 0% 0% / auto repeat border-box border-box match-source,
    url("#svg-mask") 0% 0% / auto repeat border-box border-box match-source;
}

`mask-composite` 屬性

mask 簡寫包含了 mask-composite 屬性，它定義了多個遮罩如何組合以建立最終的遮罩效果。以逗號分隔的值列表中的每個值決定了瀏覽器應該將關聯的遮罩層與它下面的遮罩層進行 add（相加）、subtract（相減）、intersect（相交）還是 exclude（排除）。與 mask-mode 和其他 mask-* 屬性類似，background 簡寫中沒有與之類似的屬性。

<div class="add">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>
<div class="subtract">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>
<div class="intersect">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>
<div class="exclude">
  <img
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>

在這個例子中，我們包含了兩個 mask-image 值，包括之前示例中的星星和漸變作為遮罩影像。

css

img {
  mask-image:
    repeating-linear-gradient(
      to bottom right,
      red 0 20px,
      #ff000055 20px 40px,
      transparent 40px 60px
    ),
    url("https://mdn.github.io/shared-assets/images/examples/mask-star.svg");
}

我們為每個影像設定了不同的 mask-composite 值。

css

.add img {
  mask-composite: add;
}
.subtract img {
  mask-composite: subtract;
}
.intersect img {
  mask-composite: intersect;
}
.exclude img {
  mask-composite: exclude;
}

div::before {
  content: "mask-composite: " attr(class);
  display: block;
  text-align: center;
  font-family: monospace;
}
body {
  flex-flow: row wrap;
}

半透明的星星遮罩會根據 mask-composite 的值，與條紋遮罩相加、相減、相交或排除。

mask-composite 屬性僅在有兩個或更多遮罩層的情況下才相關。這裡說的是“遮罩層”，而不是“遮罩影像”，因為如果包含 none，透明的黑色遮罩也會被合成。在 subtract 和 intersect 的情況下，none 值會對遮罩產生深遠的影響。例如，如果 mask-mode 解析為 luminance，減去一個黑色遮罩將移除整個遮罩（元素將被隱藏）。類似地，如果 none 是最後一層，並且該層的 mask-composite 設定為 intersect，整個元素將被隱藏。這裡，我們在前面的例子中添加了第三層，值為 none。

css

img {
  mask-image:
    url("https://mdn.github.io/shared-assets/images/examples/mask-star.svg"),
    repeating-linear-gradient(
      to bottom right,
      red 0 20px,
      #ff000055 20px 40px,
      transparent 40px 60px
    ),
    none;
}

注意 intersect 示例如何排除了所有內容，因為透明的黑色遮罩不與任何東西相交。

如果我們顛倒遮罩層的順序，我們也可以得到非常不同的結果。

<div class="subtract">
  <img
    class="gradientFirst"
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>
<div class="subtract">
  <img
    class="starFirst"
    src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
    alt="Pride flag" />
</div>

css

.gradientFirst {
  mask-image:
    repeating-linear-gradient(
      to bottom right,
      red 0 20px,
      #ff000055 20px 40px,
      transparent 40px 60px
    ),
    url("https://mdn.github.io/shared-assets/images/examples/mask-star.svg");
}
.starFirst {
  mask-image:
    url("https://mdn.github.io/shared-assets/images/examples/mask-star.svg"),
    repeating-linear-gradient(
      to bottom right,
      red 0 20px,
      #ff000055 20px 40px,
      transparent 40px 60px
    );
}

在第一個例子中，星星從條紋中減去。在第二個例子中，條紋從星星中減去。

與所有其他 mask 分量屬性一樣，mask-composite 接受一個以逗號分隔的值列表。由於該屬性影響遮罩的組合方式，因此該屬性僅與多個遮罩層相關，並且使用的值的數量比遮罩層的數量少一個。

最後一對遮罩首先被合成。然後，前一個遮罩影像與前一次的合成結果進行合成。

繼續 masked-element 示例，如果我們沒有明確設定 mask-composite 屬性，它將對每個層預設為 add，就好像我們設定了以下內容：

css

.masked-element {
  mask-image:
    url("alphaImage.png"), linear-gradient(to right, black, transparent),
    radial-gradient(circle, white 50%, transparent 75%), none, url("#svg-mask");
  mask-mode: match-source;
  mask-position: 0% 0%;
  mask-origin: border-box;
  mask-clip: border-box;
  mask-size: auto;
  mask-repeat: repeat;
  mask-composite: add;
}

在這種情況下，<mask> 元素將與 none 層合成。然後徑向漸變將與前一次合成的結果合成，依此類推。

就像我們看到的所有其他分量屬性一樣，我們可以使用 mask 簡寫：

css

.masked-element {
  mask:
    url("alphaImage.png") 0% 0% / auto repeat border-box border-box add
      match-source,
    linear-gradient(to right, black, transparent) 0% 0% / auto repeat border-box
      border-box add match-source,
    radial-gradient(circle, white 50%, transparent 75%) 0% 0% / auto repeat
      border-box border-box add match-source,
    none 0% 0% / auto repeat border-box border-box add match-source,
    url("#svg-mask") 0% 0% / auto repeat border-box border-box add match-source;
}

另見

幫助改進 MDN

瞭解如何貢獻

此頁面最後修改於 ⁨2025 年 8 月 13 日⁩，由 MDN 貢獻者修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題