@property

syntax

Описывает допустимый синтаксис свойства. Может быть <length>, <number>, <percentage>, <length-percentage>, <color>, <image>, <url>, <integer>, <angle>, <time>, <resolution>, <transform-function>, или <custom-ident>, или списком типов данных и значений ключевых слов.

Множители + (разделенные пробелами) и # (разделенные запятыми) указывают, что ожидается список значений, например, <color># означает, что ожидается список значений <color> через запятую.

Вертикальные черты (|) могут создавать условия «или» для ожидаемого синтаксиса, например, <length> | auto принимает <length> или auto, а <color># | <integer># ожидает список значений <color> через запятую или список значений <integer> через запятую.

inherits

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

initial-value

Устанавливает начальное значение свойства.

Правило @property должно содержать как описание syntax, так и inherits; при отсутствии одного из них, все правило @property считается невалидным и игнорируется. Описание initial-value также требуется, если синтаксис не является * универсальным определением синтаксиса (например, syntax: "*"). Если обязательное описание initial-value отсутствует, то всё правило @property считается невалидным и игнорируется.

Неизвестные описания невалидны и игнорируются, но не делают невалидным само правило @property.

@property = 
  @property <custom-property-name> { <declaration-list> }  

В этом примере определены два пользовательских свойства, --item-size и --item-color, которые мы будем использовать для определения размера (ширины и высоты) и цвета фона трёх следующих элементов.

<div class="container">
  <div class="item one">Item one</div>
  <div class="item two">Item two</div>
  <div class="item three">Item three</div>
</div>

Следующий код использует правило CSS @property для определения пользовательского свойства с именем --item-size. Свойство устанавливает начальное значение в 40%, ограничивая допустимые значения только значениями <percentage>. Это означает, что при использовании в качестве значения размера элемента, его размер всегда будет относительным к размеру родительского элемента. Свойство наследуется.

@property --item-size {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 40%;
}

Определяем второе пользовательское свойство --item-color с помощью JavaScript вместо CSS. Метод JavaScript registerProperty() эквивалентен правилу @property. Свойство определено с начальным значением aqua, принимает только значения <color> и не наследуется.

window.CSS.registerProperty({
  name: "--item-color",
  syntax: "<color>",
  inherits: false,
  initialValue: "aqua",
});

Мы используем два пользовательских свойства для форматирования элементов:

.container {
  display: flex;
  height: 200px;
  border: 1px dashed black;

  /* set custom property values on parent */
  --item-size: 20%;
  --item-color: orange;
}

/* use custom properties to set item size and background color */
.item {
  width: var(--item-size);
  height: var(--item-size);
  background-color: var(--item-color);
}

/* set custom property values on element itself */
.two {
  --item-size: initial;
  --item-color: inherit;
}

.three {
  /* invalid values */
  --item-size: 1000px;
  --item-color: xyz;
}

Два пользовательских свойства, --item-size: 20% и --item-color: orange; заданы для родительского элемента container, перезаписывая значения 40% и aqua по умолчанию, установленные при определении этих пользовательских свойств. Размер устанавливается как наследуемый; цвет — нет.

Для первого элемента ни одно из этих пользовательских свойств не задано. --item-size наследуется, поэтому используется значение 20% родительского элемента container. С другой стороны, свойство --item-color не наследуется, поэтому значение orange родительского элемента не учитывается. Вместо этого используется значение по умолчанию aqua.

Для второго элемента для обоих пользовательских свойств установлены глобальные ключевые слова CSS, которые являются допустимыми значениями для всех типов значений и, следовательно, допустимы независимо от значения syntax описания. --item-size установлено в initial и использует значение initial-value: 40%; из объявления @property. Значение initial означает, что используется значение initialValue свойства. --item-color установлено в inherit, явно наследуя значение orange от родительского элемента, даже несмотря на то, что пользовательское свойство по умолчанию не наследуется. Вот почему второй элемент оранжевый.

Для третьего элемента значение --item-size установлено в 1000px. Хотя 1000px — это значение <length>, объявление @property требует значения <percentage>, поэтому объявление некорректно и игнорируется, что означает использование наследуемого значения 20% родительского элемента. Значение xyz также некорректно. Так как registerProperty() установил, что --item-color не наследуется, используется значение по умолчанию aqua, а не значение родительского элемента orange.

• var()
• API свойств и значений CSS
• API отрисовки CSS
• Типизированная объектная модель CSS
• API Houdini
• Руководство по использованию пользовательских свойств CSS (переменных)
• Модуль пользовательских свойств CSS для каскадных переменных