CSS-правило @property

@property CSS правило at-rule используется для явного определения пользовательских свойств CSS, что позволяет проверять и ограничивать типы значений свойств, задавать значения по умолчанию и определять, может ли пользовательское свойство наследовать значения.

Синтаксис

@property --canBeAnything {
  syntax: "*";
  inherits: true;
}

@property --rotation {
  syntax: "<angle>";
  inherits: false;
  initial-value: 45deg;
}

@property --defaultSize {
  syntax: "<length> | <percentage>";
  inherits: true;
  initial-value: 200px;
}

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

Дескрипторы

syntax

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

inherits

Логическое значение, определяющее, наследует ли по умолчанию регистрация пользовательского свойства, заданная с помощью @property.

initial-value

Значение, задающее начальное значение свойства.

Описание

Правило at-rule @property входит в набор API CSS Houdini. Оно позволяет разработчикам явно определять пользовательские свойства CSS, что позволяет проверять и ограничивать типы значений свойств, задавать значения по умолчанию и определять, может ли пользовательское свойство наследовать значения.

Правило @property позволяет регистрировать пользовательские свойства непосредственно в таблицах стилей, не используя JavaScript. Допустимые правила @property создают зарегистрированные пользовательские свойства, что дает тот же результат, что и вызов registerProperty() с эквивалентными параметрами.

Чтобы правило @property было допустимым, должны выполняться следующие условия:

• Правило @property должно содержать оба дескриптора: syntax и inherits. Если отсутствует хотя бы один из них, все правило @property считается недопустимым и игнорируется.
• Значением syntax может быть имя типа данных (например, <color>, <length> или <number> и т. д.) с множителями (+ для списка значений, разделенных пробелами, или # для списка значений, разделенных запятыми) и комбинаторами (| для одного из нескольких типов данных), пользовательский идентификатор или универсальное определение синтаксиса (*), означающее, что синтаксис может представлять собой любую допустимую последовательность токенов. Значение является <string>. Поэтому оно должно быть заключено в кавычки.
• Дескриптор initial-value необязателен, если значение дескриптора syntax — универсальное определение синтаксиса (syntax: "*"). Если дескриптор initial-value обязателен, но не указан, все правило @property считается недопустимым и игнорируется.
• Если значение дескриптора syntax не является универсальным определением синтаксиса, значение дескриптора initial-value должно быть вычислительно независимым. Это означает, что значение можно преобразовать в вычисленное значение, не зависящее от других значений, за исключением «глобальных» определений, независимых от CSS. Например, 10px является вычислительно независимым — при преобразовании в вычисленное значение оно не меняется. 2in также допустимо, поскольку 1in всегда эквивалентно 96px. Однако 3em недопустимо, поскольку значение em зависит от font-size родительского элемента.
• Неизвестные дескрипторы недопустимы и игнорируются, но не делают правило @property недопустимым.

Если с одним и тем же именем задано несколько допустимых правил @property, применяется последнее в порядке таблицы стилей. Если пользовательские свойства с одинаковым именем зарегистрированы с помощью @property в CSS и CSS.registerProperty() в JavaScript, применяется регистрация JavaScript.

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

Примеры

Базовый пример

В этом примере мы используем правило at-rule @property, чтобы объявить два пользовательских свойства, а затем используем их в объявлениях стилей.

HTML

<p>Hello world!</p>

CSS

@property --myColor {
  syntax: "<color>";
  inherits: true;
  initial-value: rebeccapurple;
}

@property --myWidth {
  syntax: "<length> | <percentage>";
  inherits: true;
  initial-value: 200px;
}

p {
  background-color: var(--myColor);
  width: var(--myWidth);
  color: white;
}

Результат

Ширина абзаца должна составлять 200px, фон должен быть фиолетовым, а текст — белым.

Анимация значения пользовательского свойства

В этом примере мы определяем пользовательское свойство с именем --progress с помощью @property: оно принимает значения <percentage>, а его начальное значение — 25%. Мы используем --progress, чтобы задать положение цветовых маркеров в linear-gradient(), определив, где заканчивается зеленый цвет и начинается черный. Затем мы анимируем значение --progress до 100% за 2,5 секунды, создавая эффект анимированной полосы прогресса.

HTML

<div class="bar"></div>

CSS

@property --progress {
  syntax: "<percentage>";
  inherits: false;
  initial-value: 25%;
}

.bar {
  display: inline-block;
  --progress: 25%;
  width: 100%;
  height: 5px;
  background: linear-gradient(
    to right,
    #00d230 var(--progress),
    black var(--progress)
  );
  animation: progressAnimation 2.5s ease infinite;
}

@keyframes progressAnimation {
  to {
    --progress: 100%;
  }
}

Результат

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

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

См. также

• var()
• Пользовательские свойства (--*)
• Регистрация пользовательских свойств CSS
• Модуль CSS Properties and Values API
• Документация по API CSS Properties and Values
• Руководство Использование пользовательских свойств CSS (переменных)
• Модуль Пользовательские свойства CSS для каскадных переменных