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 是預設值。將一個或兩個值都設定為 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 寬（200px 寬元素的 50%）。高度預設為 auto，保持了遮罩的寬高比。在 height 的情況下，遮罩被渲染為 200px 高（400px 高容器的 50%）。寬度被明確設定為 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");
}

其中兩個 <div> 元素的 mask-size 被設定為該屬性的關鍵字值之一。第三個 <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 遮罩模組