CSS-свойство `mask-image`

Свойство mask-image CSS задаёт изображение, используемое в качестве слоя маски для элемента. Оно скрывает части элемента, к которым применена маска, в зависимости от альфа-канала изображения маски и, в зависимости от значения свойства mask-mode, яркости цветов изображения маски.

Синтаксис

/* Keyword value */
mask-image: none;

/* <mask-source> value */
mask-image: url("masks.svg#mask1");

/* <image> values */
mask-image: linear-gradient(black, transparent);
mask-image: image(url("mask.png"), skyblue);

/* Multiple values */
mask-image: url("mask.png"), linear-gradient(black 25%, transparent 35%);

/* Global values */
mask-image: inherit;
mask-image: initial;
mask-image: revert;
mask-image: revert-layer;
mask-image: unset;

Значения

none

Это ключевое слово интерпретируется как слой прозрачного чёрного изображения.

<mask-source>

Ссылка <url> на <mask> или изображение CSS.

<image>

Значение изображения, используемое в качестве слоя маски.

Описание

Свойство mask-image задаёт маску, скрывающую часть элемента, к которому она применена. Значение представляет собой разделённый запятыми список ссылок на маски. Каждая ссылка на маску — это <image>, <mask-source> или ключевое слово none.

<image> может быть изображением любого типа, включая генерируемые изображения, например градиенты CSS.

Если в значении свойства mask-image указано только одно значение и оно равно none, эффект маскирования не будет заметен. Если указано несколько значений, значение none в списке может не оказывать непосредственного эффекта, однако другие значения mask-* в той же позиции списка будут применены к слою прозрачной чёрной маски и не будут иметь визуального эффекта.

В качестве значений <image> принимаются только источники изображений, передаваемые по протоколам HTTP и HTTPS, в соответствии с политикой CORS. Изображения, загруженные локально, в том числе с использованием относительных или абсолютных протоколов file://, не принимаются и будут отображаться как прозрачные чёрные. Чтобы проверять URL-источники изображений локально, настройте локальный сервер.

В следующих случаях маска считается слоем прозрачного чёрного изображения, который ничего не показывает:

• Изображение маски пустое (имеет нулевую ширину или высоту).
• Не удалось загрузить изображение маски.
• Браузер не поддерживает формат изображения маски.
• Изображение маски не существует.
• Значение маски не указывает на изображение маски.

Значение свойства mask-mode по умолчанию — match-source, то есть режим определяется режимом самого изображения маски. Режим изображения маски обычно равен alpha, кроме случаев, когда источником маски является элемент SVG <mask>. В этом случае режим равен luminance, если только он не изменён на alpha с помощью свойства CSS mask-type или атрибута SVG mask-type.

Значение mask-mode имеет большое значение, поскольку оно определяет, зависит ли эффект маскирования только от значений альфа-канала источника изображения или от сочетания этих значений и яркости маски (светлоты или темноты цветов, из которых состоит mask-image):

• Во всех случаях важна прозрачность альфа-канала маски: части элемента, закрытые непрозрачными участками mask-image, будут отображаться, а части, закрытые прозрачными участками изображения, будут скрыты.
• Если значение mask-mode равно или разрешается в alpha, учитывается только альфа-канал цветов; оттенок, светлота и другие параметры не имеют значения.
• Если свойству mask-mode задано значение luminance или оно используется по умолчанию, значение маскирования определяется яркостью каждого цвета, умноженной на его значение альфа-канала. Значение mask-mode разрешается в luminance, если ему явно задано это значение или если свойству задано значение match-source, а источником mask-image является элемент SVG <mask>, для которого свойство mask-type или атрибут mask-type явно не установлены в alpha.

Формальное определение

Формальный синтаксис

mask-image = 
  <mask-reference>#

<mask-reference> = 
  none |
  <image> |
  <mask-source>

<image> = 
  <url> |
  <image()> |
  <image-set()> |
  <element()> |
  <paint()> |
  <cross-fade()> |
  <gradient>

<mask-source> = 
  <url>

<image()> = 
  image( <image-tags>? [ <image-src>? , <color>? ]! )

<image-set()> = 
  image-set( <image-set-option># )

<element()> = 
  element( <id-selector> )

<paint()> = 
  paint( <ident>, <declaration-value>? )

<cross-fade()> = 
  cross-fade( <cf-mixing-image> , <cf-final-image>? )

<gradient> = 
  <linear-gradient()> |
  <repeating-linear-gradient()> |
  <radial-gradient()> |
  <repeating-radial-gradient()> |
  <conic-gradient()> |
  <repeating-conic-gradient()>

<image-tags> = 
  ltr |
  rtl

<image-src> = 
  <url> |
  <string>

<color> = 
  <color-base> |
  currentColor |
  <system-color> |
  <light-dark()> |
  <deprecated-system-color>

<image-set-option> = 
  [ <image> | <string> ] [ <resolution> || type(<string>) ]

<id-selector> = 
  <hash-token>

<cf-mixing-image> = 
  <percentage>? &&
  <image>

<cf-final-image> = 
  <image> |
  <color>

<linear-gradient()> = 
  linear-gradient( [ <linear-gradient-syntax> ] )

<repeating-linear-gradient()> = 
  repeating-linear-gradient( [ <linear-gradient-syntax> ] )

<radial-gradient()> = 
  radial-gradient( [ <radial-gradient-syntax> ] )

<repeating-radial-gradient()> = 
  repeating-radial-gradient( [ <radial-gradient-syntax> ] )

<conic-gradient()> = 
  conic-gradient( [ <conic-gradient-syntax> ] )

<repeating-conic-gradient()> = 
  repeating-conic-gradient( [ <conic-gradient-syntax> ] )

<color-base> = 
  <hex-color> |
  <color-function> |
  <named-color> |
  <color-mix()> |
  transparent

<system-color> = 
  AccentColor |
  AccentColorText |
  ActiveText |
  ButtonBorder |
  ButtonFace |
  ButtonText |
  Canvas |
  CanvasText |
  Field |
  FieldText |
  GrayText |
  Highlight |
  HighlightText |
  LinkText |
  Mark |
  MarkText |
  SelectedItem |
  SelectedItemText |
  VisitedText

<light-dark()> = 
  light-dark( <color>, <color> )

<deprecated-system-color> = 
  ActiveBorder |
  ActiveCaption |
  AppWorkspace |
  Background |
  ButtonHighlight |
  ButtonShadow |
  CaptionText |
  InactiveBorder |
  InactiveCaption |
  InactiveCaptionText |
  InfoBackground |
  InfoText |
  Menu |
  MenuText |
  Scrollbar |
  ThreeDDarkShadow |
  ThreeDFace |
  ThreeDHighlight |
  ThreeDLightShadow |
  ThreeDShadow |
  Window |
  WindowFrame |
  WindowText

<linear-gradient-syntax> = 
  [ [ <angle> | <zero> | to <side-or-corner> ] || <color-interpolation-method> ]? , <color-stop-list>

<radial-gradient-syntax> = 
  [ [ [ <radial-shape> || <radial-size> ]? [ at <position> ]? ] || <color-interpolation-method> ]? , <color-stop-list>

<conic-gradient-syntax> = 
  [ [ [ from [ <angle> | <zero> ] ]? [ at <position> ]? ] || <color-interpolation-method> ]? , <angular-color-stop-list>

<color-function> = 
  <rgb()> |
  <rgba()> |
  <hsl()> |
  <hsla()> |
  <hwb()> |
  <lab()> |
  <lch()> |
  <oklab()> |
  <oklch()> |
  <color()>

<named-color> = 
  aliceblue |
  antiquewhite |
  aqua |
  aquamarine |
  azure |
  beige |
  bisque |
  black |
  blanchedalmond |
  blue |
  blueviolet |
  brown |
  burlywood |
  cadetblue |
  chartreuse |
  chocolate |
  coral |
  cornflowerblue |
  cornsilk |
  crimson |
  cyan |
  darkblue |
  darkcyan |
  darkgoldenrod |
  darkgray |
  darkgreen |
  darkgrey |
  darkkhaki |
  darkmagenta |
  darkolivegreen |
  darkorange |
  darkorchid |
  darkred |
  darksalmon |
  darkseagreen |
  darkslateblue |
  darkslategray |
  darkslategrey |
  darkturquoise |
  darkviolet |
  deeppink |
  deepskyblue |
  dimgray |
  dimgrey |
  dodgerblue |
  firebrick |
  floralwhite |
  forestgreen |
  fuchsia |
  gainsboro |
  ghostwhite |
  gold |
  goldenrod |
  gray |
  green |
  greenyellow |
  grey |
  honeydew |
  hotpink |
  indianred |
  indigo |
  ivory |
  khaki |
  lavender |
  lavenderblush |
  lawngreen |
  lemonchiffon |
  lightblue |
  lightcoral |
  lightcyan |
  lightgoldenrodyellow |
  lightgray |
  lightgreen |
  lightgrey |
  lightpink |
  lightsalmon |
  lightseagreen |
  lightskyblue |
  lightslategray |
  lightslategrey |
  lightsteelblue |
  lightyellow |
  lime |
  limegreen |
  linen |
  magenta |
  maroon |
  mediumaquamarine |
  mediumblue |
  mediumorchid |
  mediumpurple |
  mediumseagreen |
  mediumslateblue |
  mediumspringgreen |
  mediumturquoise |
  mediumvioletred |
  midnightblue |
  mintcream |
  mistyrose |
  moccasin |
  navajowhite |
  navy |
  oldlace |
  olive |
  olivedrab |
  orange |
  orangered |
  orchid |
  palegoldenrod |
  palegreen |
  paleturquoise |
  palevioletred |
  papayawhip |
  peachpuff |
  peru |
  pink |
  plum |
  powderblue |
  purple |
  rebeccapurple |
  red |
  rosybrown |
  royalblue |
  saddlebrown |
  salmon |
  sandybrown |
  seagreen |
  seashell |
  sienna |
  silver |
  skyblue |
  slateblue |
  slategray |
  slategrey |
  snow |
  springgreen |
  steelblue |
  tan |
  teal |
  thistle |
  tomato |
  turquoise |
  violet |
  wheat |
  white |
  whitesmoke |
  yellow |
  yellowgreen

<color-mix()> = 
  color-mix( <color-interpolation-method> , [ <color> && <percentage [0,100]>? ]#{2})

<side-or-corner> = 
  [ left | right ] ||
  [ top | bottom ]

<color-interpolation-method> = 
  in [ <rectangular-color-space> | <polar-color-space> <hue-interpolation-method>? | <custom-color-space> ]

<color-stop-list> = 
  <linear-color-stop> , [ <linear-color-hint>? , <linear-color-stop> ]#?

<radial-shape> = 
  circle |
  ellipse

<radial-size> = 
  <radial-extent> |
  <length [0,∞]> |
  <length-percentage [0,∞]>{2}

<position> = 
  [ [ left | center | right ] || [ top | center | bottom ] | [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ]? | [ [ left | right ] <length-percentage> ] && [ [ top | bottom ] <length-percentage> ] ]

<angular-color-stop-list> = 
  <angular-color-stop> , [ <angular-color-hint>? , <angular-color-stop> ]#?

<rgb()> = 
  rgb( <percentage>#{3} , <alpha-value>? ) |
  rgb( <number>#{3} , <alpha-value>? ) |
  rgb( [ <number> | <percentage> | none ]{3} [ / [ <alpha-value> | none ] ]? )

<rgba()> = 
  rgba( <percentage>#{3} , <alpha-value>? ) |
  rgba( <number>#{3} , <alpha-value>? ) |
  rgba( [ <number> | <percentage> | none ]{3} [ / [ <alpha-value> | none ] ]? )

<hsl()> = 
  hsl( <hue>, <percentage>, <percentage>, <alpha-value>? ) |
  hsl( [ <hue> | none ] [ <percentage> | <number> | none ] [ <percentage> | <number> | none ] [ / [ <alpha-value> | none ] ]? )

<hsla()> = 
  hsla( <hue>, <percentage>, <percentage>, <alpha-value>? ) |
  hsla( [ <hue> | none ] [ <percentage> | <number> | none ] [ <percentage> | <number> | none ] [ / [ <alpha-value> | none ] ]? )

<hwb()> = 
  hwb( [ <hue> | none ] [ <percentage> | <number> | none ] [ <percentage> | <number> | none ] [ / [ <alpha-value> | none ] ]? )

<lab()> = 
  lab( [<percentage> | <number> | none] [ <percentage> | <number> | none] [ <percentage> | <number> | none] [ / [<alpha-value> | none] ]? )

<lch()> = 
  lch( [<percentage> | <number> | none] [ <percentage> | <number> | none] [ <hue> | none] [ / [<alpha-value> | none] ]? )

<oklab()> = 
  oklab( [ <percentage> | <number> | none] [ <percentage> | <number> | none] [ <percentage> | <number> | none] [ / [<alpha-value> | none] ]? )

<oklch()> = 
  oklch( [ <percentage> | <number> | none] [ <percentage> | <number> | none] [ <hue> | none] [ / [<alpha-value> | none] ]? )

<color()> = 
  color( [ from <color> ]? <colorspace-params> [ / [ <alpha-value> | none ] ]? )

<rectangular-color-space> = 
  srgb |
  srgb-linear |
  display-p3 |
  display-p3-linear |
  a98-rgb |
  prophoto-rgb |
  rec2020 |
  lab |
  oklab |
  xyz |
  xyz-d50 |
  xyz-d65

<polar-color-space> = 
  hsl |
  hwb |
  lch |
  oklch

<hue-interpolation-method> = 
  [ shorter | longer | increasing | decreasing ] hue

<custom-color-space> = 
  <dashed-ident>

<linear-color-stop> = 
  <color> <color-stop-length>?

<linear-color-hint> = 
  <length-percentage>

<radial-extent> = 
  closest-corner |
  closest-side |
  farthest-corner |
  farthest-side

<length-percentage> = 
  <length> |
  <percentage>

<angular-color-stop> = 
  <color> <color-stop-angle>?

<angular-color-hint> = 
  <angle-percentage> |
  <zero>

<alpha-value> = 
  <number> |
  <percentage>

<hue> = 
  <number> |
  <angle>

<colorspace-params> = 
  [<custom-params> | <predefined-rgb-params> | <xyz-params>]

<color-stop-length> = 
  <length-percentage>{1,2}

<color-stop-angle> = 
  [ <angle-percentage> | <zero> ]{1,2}

<angle-percentage> = 
  <angle> |
  <percentage>

<custom-params> = 
  <dashed-ident> [ <number> | <percentage> | none ]+

<predefined-rgb-params> = 
  <predefined-rgb> [ <number> | <percentage> | none ]{3}

<xyz-params> = 
  <xyz> [ <number> | <percentage> | none ]{3}

<predefined-rgb> = 
  srgb |
  srgb-linear |
  display-p3 |
  display-p3-linear |
  a98-rgb |
  prophoto-rgb |
  rec2020

<xyz> = 
  xyz |
  xyz-d50 |
  xyz-d65

Примеры

Градиент в качестве изображения маски

В этом примере мы используем значение <image> в качестве маски, задавая радиальный градиент CSS radial gradient как изображение маски, чтобы создать круглое изображение с мягкими краями.

HTML

Мы добавляем элемент HTML <img>, который также будет использоваться во всех остальных примерах.

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

CSS

Мы используем функцию CSS radial-gradient(), чтобы создать маску с чёрным кругом, радиус которого равен половине ширины маски, с переходом к прозрачности на протяжении следующих 10%.

img {
  mask-image: radial-gradient(black 50%, transparent 60%);
}

Результат

Часть исходного элемента, закрытая чёрным кругом, полностью непрозрачна; по мере того как маска становится прозрачной, она постепенно исчезает.

Ресурс изображения в качестве изображения маски

В этом примере в качестве изображения маски используется внешний файл SVG <mask-source>.

HTML

Мы добавляем то же изображение, что и в предыдущем примере. Также мы добавили изображение, которое будем использовать в качестве маски: звезду со значением fill-opacity 0.5, то есть с непрозрачностью 50%.

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

<img
  src="https://mdn.github.io/shared-assets/images/examples/mask-star.svg"
  alt="A star" />

CSS

Мы применяем mask-star.svg в качестве маски к первому изображению:

img:first-of-type {
  mask-image: url("https://mdn.github.io/shared-assets/images/examples/mask-star.svg");
}

Результат

Маска полупрозрачная, поэтому цвета не такие яркие, как в предыдущем примере. Видимая часть изображения имеет непрозрачность 50% — такую же, как у применённой маски. Маска меньше изображения, поэтому по умолчанию она повторяется. Для управления повторением можно было бы использовать mask-repeat, а для изменения размера маски — mask-size; последний вариант мы используем в следующем примере.

Несколько масок

В этом примере показано применение нескольких масок.

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

CSS

Мы применяем две маски — ту же полупрозрачную маску SVG, что и в предыдущем примере, и repeating-radial-gradient(). Мы управляем размером масок с помощью свойства mask-size. Поскольку размер первой маски не равен 100%, мы центрируем маски и отключаем их повторение с помощью свойств mask-position и mask-repeat соответственно.

img {
  mask-size: 95%, 100%;
  mask-position: center;
  mask-repeat: no-repeat;
  mask-image:
    url("https://mdn.github.io/shared-assets/images/examples/mask-star.svg"),
    repeating-radial-gradient(transparent 0 5px, black 5px 10px);
}

Результат

Маскирование с помощью SVG <mask>

В этом примере показано использование элементов SVG <mask> в качестве масок. В данном случае цвет маски имеет значение, поскольку для масок SVG значением свойства mask-type по умолчанию является luminance. Это означает, что непрозрачные белые участки (яркость 100%) будут замаскированы и видимы, прозрачные и чёрные участки (яркость 0%) будут обрезаны, а всё, что находится между ними, будет замаскировано частично.

HTML

Мы добавили по элементу id для каждого из четырёх изображений, а также SVG с таким же количеством элементов <mask>.

<img
  id="green"
  src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
  alt="Pride flag" />
<img
  id="stroke"
  src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
  alt="Pride flag" />
<img
  id="both"
  src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
  alt="Pride flag" />
<img
  id="alphaMode"
  src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
  alt="Pride flag" />

<svg height="0" width="0">
  <mask id="greenMask">
    <path
      d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z"
      fill="green" />
  </mask>
  <mask id="strokeMask">
    <path
      d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z"
      fill="none"
      stroke="white"
      stroke-width="20" />
  </mask>
  <mask id="bothMask">
    <path
      d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z"
      fill="green"
      stroke="white"
      stroke-width="20" />
  </mask>
  <mask id="black">
    <path
      d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z"
      fill="black" />
  </mask>
</svg>

<p>
  <label>
    <input type="checkbox" />
    Set the <code>mask-mode</code> to <code>alpha</code>.
  </label>
</p>

CSS

Мы применяем разное значение <mask> к каждому <img>. По умолчанию не будет видна ни одна часть последнего изображения, у которого заливка black. В этом случае, хотя все используемые в примере цвета полностью непрозрачны, для mask-mode по умолчанию задано значение match-type, которое здесь разрешается в luminance.

#green {
  mask-image: url("#greenMask");
}
#stroke {
  mask-image: url("#strokeMask");
}
#both {
  mask-image: url("#bothMask");
}
#alphaMode {
  mask-image: url("#black");
}

body:has(:checked) img {
  mask-mode: alpha;
}

Значения яркости для black, white и green равны 0, 100 и 46.228 соответственно. Это означает, что будут видны участки с белой маской, а участки с чёрной или полностью прозрачной маской будут обрезаны (не видны). Участки с зелёной маской будут видны, но светлее — так же, как если бы белая маска имела непрозрачность 46,228%.

Результат

Установите или снимите флажок, чтобы переключить значение mask-mode между alpha (флажок установлен) и начальным значением, которое разрешается в luminance (флажок снят). При использовании alpha цвет маски не имеет значения — важна только прозрачность альфа-канала. Когда значение разрешается в luminance, видны участки white, участки black не видны, а участки green видны с непрозрачностью, соответствующей яркости цвета green. Если для mask-mode задано значение alpha, цвета эквивалентны, поскольку все они полностью непрозрачны.

Спецификации

Совместимость с браузерами

См. также

• сокращённое свойство mask
• mask-origin
• mask-position
• mask-repeat
• mask-size
• mask-border
• clip-path
• background-image
• Введение в маскирование CSS
• Свойства маски CSS mask
• Объявление нескольких масок
• Модуль маскирования CSS