CSS-правило `@function`

@function — это CSS at-правило, позволяющее определять пользовательские функции CSS. После определения пользовательскую функцию можно вызывать с помощью синтаксиса <dashed-function> (например, --my-function(30px, 3)) в значении любого свойства.

Синтаксис

@function --function-name(<function-parameter>#?) [returns <css-type>]? {
  <declaration-rule-list>
}

<function-parameter> = --param-name <css-type>? [ : <default-value> ]?

Различные части синтаксиса @function описаны ниже:

--function-name

Идентифицирующее имя функции — <dashed-ident>, которое начинается с --, за которым следует допустимый идентификатор, определённый пользователем. Имя чувствительно к регистру.

<function-parameter>#? Необязательно

Ноль или более определений параметров функции. Несколько определений параметров разделяются запятыми. Каждый параметр состоит из следующих частей:

--param-name

Имя пользовательского свойства CSS, идентифицирующее параметр, — <dashed-ident>, которое начинается с --, за которым следует допустимый идентификатор, определённый пользователем. Имя чувствительно к регистру. Параметры функции можно считать пользовательскими свойствами, область действия которых ограничена телом функции.

<css-type> Необязательно

Тип данных CSS или функция type(), задающая допустимые типы данных параметра. Если этот тип не указан, для параметра допустим любой тип данных (то же самое, что указать type(*)).

<default-value> Необязательно

Значение CSS, задающее значение по умолчанию для параметра, если при вызове функции оно не указано. Если <css-type> задан, это значение должно быть допустимым согласно ему. Значение по умолчанию отделяется от остальных частей определения параметра двоеточием (:).

[returns <css-type>]? Необязательно

Тип данных CSS или функция type(), которой предшествует ключевое слово returns и которая задаёт допустимые типы возвращаемого значения параметра. Если тип не указан, для параметра допустим любой тип данных (то же самое, что указать returns type(*)). Однако следует учитывать, что функция будет недопустимой, если возвращаемый тип не совпадает с типом, полученным из дескриптора result.

<declaration-rule-list>

Одно или несколько объявлений CSS или at-правил, составляющих тело функции с её логикой. Включённые объявления могут содержать:

• Пользовательские свойства CSS, область действия которых ограничена телом функции.
• Дескриптор result, расположенный непосредственно внутри at-правила @function или внутри вложенного at-правила.

Дескрипторы

result

Допустимое значение свойства, задающее результат, возвращаемый пользовательской функцией CSS. Выражение, содержащееся в значении, вычисляется, и результат возвращается.

Описание

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

Типичная функция CSS выглядит так:

@function --transparent(--color, --alpha) {
  result: oklch(from var(--color) l c h / var(--alpha));
}

Функция называется --transparent и принимает два пользовательских свойства в качестве параметров — --color и --alpha, которые можно использовать в теле функции. Тело состоит из одной строки — дескриптора result, задающего значение, возвращаемое функцией. В значении дескриптора result используется синтаксис относительных цветов CSS, чтобы преобразовать входное значение --color в цвет oklch() со значением альфа-канала, указанным во входном значении --alpha.

Затем эту функцию можно вызывать везде, где нужно получить полупрозрачную версию существующего цвета, например:

section {
  --base-color: #faa6ff;
  background-color: --transparent(var(--base-color), 0.8);
}

Функция вызывается с помощью синтаксиса <dashed-function>: это имя функции, за которым следуют круглые скобки. Нужные значения аргументов указываются внутри скобок.

Задание типов данных

Для параметров функции и возвращаемых значений можно задавать типы данных. Например:

@function --transparent(--color <color>, --alpha <number>) returns <color> {
  result: oklch(from var(--color) l c h / var(--alpha));
}

Теперь функция будет возвращать допустимое значение, только если входные аргументы являются соответственно color и <number>, а result — это color. В противном случае, например:

section {
  --base-color: #faa6ff;
  background-color: --transparent(var(--base-color), 50%);
}

значение станет недопустимым на этапе вычисления (поскольку указанный аргумент --alpha — это <percentage>, а не ожидаемый <number>), и в итоге для background-color будет задано значение transparent.

Можно указать несколько допустимых типов данных с помощью функции type(), используя символ | в качестве разделителя. Например:

@function --transparent(--color <color>, --alpha type(<number> | <percentage>))
  returns <color> {
  result: oklch(from var(--color) l c h / var(--alpha));
}

После этого вызов функции --transparent(var(--base-color), 50%) станет допустимым.

Задание значений по умолчанию

Для параметров также можно задать значения по умолчанию, указав их после двоеточия в конце определения. Например:

@function --transparent(--color <color>, --alpha <number>: 0.8) returns <color> {
  result: oklch(from var(--color) l c h / var(--alpha));
}

Теперь значением по умолчанию для параметра --alpha будет 0.8. Чтобы использовать это значение, при вызове функции можно не указывать второй аргумент:

section {
  --base-color: #faa6ff;
  background-color: --transparent(var(--base-color));
}

Передача аргументов, содержащих запятые

В следующем примере функция --max-plus-x() принимает в качестве аргументов список длин, разделённых запятыми, и одну длину. Она использует функцию CSS max(), чтобы определить наибольшую длину в списке, прибавляет к ней отдельную длину и возвращает результат.

@function --max-plus-x(--list <length>#, --x <length>) {
  result: calc(max(var(--list)) + var(--x));
}

Первый аргумент должен быть списком, разделённым запятыми, но его можно ошибочно интерпретировать как три отдельных аргумента. Чтобы избежать этой проблемы, при передаче значения в вызов функции можно заключить его в фигурные скобки:

div {
  width: --max-plus-x({1px, 7px, 2px}, 3px); /* 10px */
}

Включение пользовательских свойств в функции

Как мы уже видели, параметры функции задаются как пользовательские свойства, которые затем доступны внутри тела функции.

В теле функции также можно задавать пользовательские свойства, которые будут действовать как локальные константы. В следующем примере мы определяем функцию --anim-1s(), возвращающую сокращённое значение animation, в котором длительность и функция плавности всегда одинаковы, а изменяются только имя и количество повторений анимации.

@function --anim-1s(--animation, --count) {
  --duration: 1s;
  --easing: linear;
  result: var(--animation) var(--duration) var(--count) var(--easing);
}

Такой подход позволяет записывать более простой и выразительный синтаксис анимаций, если вы знаете, что длительность и функция плавности должны быть неизменными:

animation: --anim-1s(bounce, 2);

Также следует отметить, что одну пользовательскую функцию можно вызывать из другой. В таких случаях пользовательская функция может обращаться к локальным переменным и параметрам функций, находящихся выше в стеке вызовов. Здесь параметр и локальное пользовательское свойство внешней функции будут доступны в области видимости внутренней функции:

@function --outer(--outer-arg) {
  --outer-local: 2;
  result: --inner();
}

@function --inner() returns <number> {
  result: calc(var(--outer-arg) + var(--outer-local));
}

div {
  z-index: --outer(1); /* 3 */
}

Кроме того, пользовательские свойства, определённые для того же элемента, на котором вызывается пользовательская функция, также будут ей доступны:

@function --double-z() returns <number> {
  result: calc(var(--z) * 2);
}

div {
  --z: 3;
  z-index: --double-z(); /* 6 */
}

Если пользовательское свойство с одним и тем же именем определено в нескольких местах, параметры функции имеют приоритет над пользовательскими свойствами, заданными для того же элемента, а локальные пользовательские свойства, определённые в теле функции, имеют приоритет над обоими. В следующем примере функция --add-a-b-c() использует свойство --a из пользовательского свойства правила div, свойство --b из параметра функции и локальное пользовательское свойство --c.

@function --add-a-b-c(--b, --c) {
  --c: 300;
  result: calc(var(--a) + var(--b) + var(--c));
}

div {
  --a: 1;
  --b: 2;
  --c: 3;
  z-index: --add-a-b-c(20, 30); /* 321 */
}

Добавление сложной логики

В функции можно добавлять более сложную логику с помощью таких конструкций, как at-правила @media и функции if(). Например, следующая функция принимает два аргумента: один для макета на узком экране, а другой — для макета на широком экране. По умолчанию она возвращает второй аргумент, но возвращает первый, если ширина области просмотра меньше 700px, что определяется с помощью медиазапроса.

@function --narrow-wide(--narrow, --wide) {
  result: var(--wide);
  @media (width < 700px) {
    result: var(--narrow);
  }
}

Для задания разных результатов при разных исходах логики можно включить несколько дескрипторов result.

Пользовательскую функцию CSS можно переписать, используя вместо этого функцию if():

@function --narrow-wide(--narrow, --wide) {
  result: if(media(width < 700px): var(--narrow) ; else: var(--wide));
}

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

Примеры

Больше примеров см. в руководстве «Использование пользовательских функций CSS».

Базовое использование @function

В этом примере показана простая функция, которая удваивает переданное ей значение.

HTML

В разметке есть элемент <p>, содержащий текст:

<p>Some content</p>

CSS

Сначала в таблице стилей мы определяем пользовательскую функцию CSS. Функция называется --double и принимает один параметр любого типа, который мы назвали --value. В теле функции мы добавляем дескриптор result, использующий функцию calc() для удвоения переданного аргумента:

@function --double(--value) {
  result: calc(var(--value) * 2);
}

Затем мы определяем пользовательское свойство --base-spacing со значением 10px. Мы задаём это свойство для значения border-radius, а для значения padding удваиваем его с помощью пользовательской функции --double().

html,
body {
  height: 100%;
}

body {
  margin: 0;
  display: grid;
  place-items: center;
  font-family: system-ui;
}

p {
  --base-spacing: 10px;
  border-radius: var(--base-spacing);
  padding: --double(var(--base-spacing));
  width: 50%;
  background-color: wheat;
}

Результат

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

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

См. также

• Пользовательские свойства CSS
• <dashed-function>: тип данных
• функция type()
• Использование пользовательских функций CSS
• Модуль пользовательских функций и примесей CSS