Функция CSS `var()`

var() CSS функцию можно использовать для вставки значения пользовательского свойства (иногда называемого «переменной CSS») вместо любой части значения другого свойства.

Функцию var() нельзя использовать в именах свойств, селекторах или где-либо ещё, кроме значений свойств. (Обычно это приводит к синтаксической ошибке или к значению, смысл которого не связан с переменной.)

Попробуйте

border-color: var(--color-a);

border-color: var(--color-b);

border-color: var(--color-c);

<section class="default-example" id="default-example">
  <div id="example-element">
    Three color options have been set on the :root use these to change the
    border color.
  </div>
</section>

:root {
  --color-a: pink;
  --color-b: green;
  --color-c: rebeccapurple;
}

#example-element {
  border: 10px solid black;
  padding: 10px;
}

Синтаксис

/* Basic usage */
var(--custom-prop);

/* With fallback */
var(--custom-prop,);  /* empty value as fallback */
var(--custom-prop, initial); /* initial value of the property as fallback */
var(--custom-prop, red);
var(--custom-prop, var(--default-value));
var(--custom-prop, var(--default-value, red));

Первый аргумент функции — имя пользовательского свойства, значение которого нужно подставить. Необязательный второй аргумент служит резервным значением. Оно используется, если у указанного пользовательского свойства нет допустимого значения — того, что спецификация называет гарантированно недопустимым значением. На практике это означает, что резервное значение используется, когда:

• Пользовательское свойство не объявлено в правиле, применяемом к элементу, и не зарегистрировано (с помощью @property) с дескриптором initial-value.
• Для пользовательского свойства задано ключевое слово initial, и оно не является зарегистрированным пользовательским свойством с initial-value. Если задать для незарегистрированного пользовательского свойства значение initial, оно сбросится к гарантированно недопустимому значению.
• Объявленное значение пользовательского свойства недопустимо на этапе вычисления значения — например, из-за циклической зависимости между пользовательскими свойствами, — а свойство не зарегистрировано или зарегистрировано с универсальным синтаксисом *.

Если пользовательское свойство зарегистрировано с помощью @property с неуниверсальным синтаксисом syntax и initial-value, это начальное значение подставляется, когда не применяется ни одно другое объявление. В этом случае резервное значение не используется.

Другие глобальные ключевые слова CSS — inherit, unset, revert, revert-layer и revert-rule — при задании в качестве значения пользовательского свойства ведут себя так же, как и для любого другого свойства. Они могут разрешить пользовательское свойство в унаследованное или ранее полученное в результате каскадирования значение, а не в гарантированно недопустимое значение, поэтому не обязательно активируют резервное значение. Например, если в одном слое каскада для --foo задано значение revert-layer, а в другом — цвет, var(--foo) разрешается в значение цвета, а не в резервное значение.

Синтаксис резервного значения, как и синтаксис пользовательских свойств, допускает запятые. Например, var(--foo, red, blue) задаёт резервное значение red, blue; то есть всё, что находится между первой запятой и концом функции, считается резервным значением.

Значения

<custom-property-name>

Имя пользовательского свойства, представленное идентификатором, который начинается с двух дефисов. Пользовательские свойства предназначены исключительно для авторов и пользователей; CSS никогда не придаст им иного значения, кроме описанного здесь.

<declaration-value>

Резервное значение пользовательского свойства, используемое, когда указанное пользовательское свойство имеет гарантированно недопустимое значение (условия, при которых это происходит, описаны в разделе «Синтаксис» выше). Это значение может содержать любые символы, кроме некоторых символов со специальным значением, таких как символы новой строки, незакрытые закрывающие скобки, то есть ), ] или }, точки с запятой верхнего уровня и восклицательные знаки. Резервное значение само может быть пользовательским свойством с синтаксисом var(). Если резервное значение не указано, а пользовательское свойство имеет гарантированно недопустимое значение, функция var() разрешается в недопустимое значение.

Примечание: var(--a,) — допустимая запись. Она указывает, что если пользовательское свойство --a имеет гарантированно недопустимое значение, вместо var() ничего подставлять не нужно.

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

<var()> = 
  var( <custom-property-name> , <declaration-value>? )

Примеры

Использование пользовательского свойства, заданного в :root

CSS

:root {
  --main-bg-color: pink;
}

body {
  background-color: var(--main-bg-color);
}

Результат

Здесь значение свойства background-color задано с помощью пользовательского свойства --main-bg-color. Поэтому цвет фона элемента body в HTML будет розовым.

Использование пользовательского свойства до того, как оно задано

CSS

body {
  background-color: var(--main-bg-color);
}

:root {
  --main-bg-color: pink;
}

Результат

В этом примере цвет фона элемента body в HTML будет розовым, даже если пользовательское свойство задано позже.

Использование пользовательского свойства, заданного в другом файле

HTML

<!doctype html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="1.css" />
    <link rel="stylesheet" href="2.css" />
  </head>
  <body></body>
</html>

CSS

/* 1.css */
body {
  background-color: var(--main-bg-color);
}

/* 2.css */
:root {
  --main-bg-color: pink;
}

Результат

В этом случае цвет фона элемента body в HTML будет розовым, даже если пользовательское свойство объявлено в другом файле.

Пользовательские свойства с резервными значениями на случай, если свойство не задано

HTML

<div class="component">
  <h1 class="header">Header</h1>
  <p class="text">Text</p>
</div>

CSS

/* In the component's style: */
.component .header {
  /* header-color isn't set, and so remains blue, the fallback value */
  color: var(--header-color, blue);
}

.component .text {
  color: var(--text-color, black);
}

/* In the larger application's style: */
.component {
  --text-color: #008800;
}

Результат

Поскольку --header-color не задано, текст «Header» будет синим — это резервное значение.

Использование пользовательского свойства в качестве резервного значения

CSS

:root {
  --backup-bg-color: teal;
}

body {
  background-color: var(--main-bg-color, var(--backup-bg-color, white));
}

Результат

Поскольку --main-bg-color не задано, свойство background-color элемента body получит резервное значение --backup-bg-color, которое соответствует бирюзовому цвету.

Недопустимые значения

Функции var() могут разрешаться в недопустимые значения, если:

• Пользовательское свойство не определено, и резервное значение не указано.
• Пользовательское свойство определено, но его значение недопустимо для свойства, в котором оно используется.

В таком случае свойство считается имеющим значение unset. Это происходит потому, что переменные не могут «завершить обработку с ошибкой на раннем этапе», как это могут сделать другие синтаксические ошибки. К тому времени, когда пользовательский агент обнаруживает недопустимое значение свойства, остальные значения, полученные в результате каскадирования, уже отброшены.

Например:

HTML

<p class="p1">Undefined variable</p>
<p class="p2">Invalid variable</p>
<p class="p3">Invalid literal color</p>

CSS

p {
  color: red;
}

.p1 {
  color: var(--invalid-color);
}

.p2 {
  --invalid-color: 20px;
  color: var(--invalid-color);
}

.p3 {
  color: 20px;
}

Результат

Обратите внимание: абзацы с var() сбрасываются до чёрного цвета по умолчанию, а абзац с недопустимым буквальным значением цвета остаётся красным, поскольку объявление color: 20px просто игнорируется.

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

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

См. также

• env(…) — доступные только для чтения переменные окружения, контролируемые пользовательским агентом.
• Использование пользовательских свойств CSS (переменных)
• @property — директива at-rule
• Регистрация пользовательских свойств CSS
• Пользовательские свойства CSS для каскадируемых переменных — модуль