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 遮罩模块