Мастерство CSS: Регистрация пользовательских свойств с помощью @property

Пользовательские свойства (также известные как CSS-переменные) произвели революцию в том, как мы пишем и поддерживаем CSS. Они позволяют нам определять повторно используемые значения, делая наши таблицы стилей более гибкими и удобными в сопровождении. Но что, если бы вы могли пойти дальше простого определения значений? Что, если бы вы могли определять тип значения, которое содержит пользовательское свойство, а также его начальное значение и поведение наследования? Именно здесь на помощь приходит @property.

Что такое @property?

@property — это at-правило в CSS, которое позволяет явно зарегистрировать пользовательское свойство в браузере. Этот процесс регистрации предоставляет браузеру информацию об ожидаемом типе свойства, его начальном значении и о том, должно ли оно наследоваться от родительского элемента. Это открывает несколько расширенных возможностей, в том числе:

• Проверка типов: Гарантирует, что пользовательскому свойству присваивается значение правильного типа.
• Анимация: Позволяет создавать плавные переходы и анимации для пользовательских свойств определённых типов, таких как числа или цвета.
• Значения по умолчанию: Предоставляет резервное значение, если пользовательское свойство не определено явно.
• Контроль наследования: Определяет, наследует ли пользовательское свойство своё значение от родительского элемента.

Считайте это добавлением типобезопасности к вашим CSS-переменным. Это позволяет создавать более надёжные и предсказуемые таблицы стилей.

Синтаксис @property

Правило @property имеет следующий базовый синтаксис:

@property --property-name {
  syntax: '';
  inherits: true | false;
  initial-value: ;
}

Давайте разберём каждую часть:

• --property-name: Имя пользовательского свойства, которое вы хотите зарегистрировать. Оно должно начинаться с двух дефисов (--).
• syntax: Определяет ожидаемый тип значения для свойства. Это крайне важно для проверки типов и анимации. Мы подробно рассмотрим доступные значения синтаксиса ниже.
• inherits: Логическое значение, указывающее, должно ли свойство наследоваться от своего родительского элемента. По умолчанию равно false, если не указано.
• initial-value: Значение по умолчанию для свойства, если оно не задано явно для элемента. Это гарантирует, что резервное значение всегда будет доступно.

Понимание дескриптора syntax

Дескриптор syntax — это самая важная часть правила @property. Он сообщает браузеру, какой тип значения ожидать для пользовательского свойства. Вот некоторые из распространённых значений синтаксиса:

• *: Разрешает любое значение. Это самый разрешительный синтаксис, который по сути дублирует поведение стандартной CSS-переменной без регистрации. Используйте его с осторожностью.
• <length>: Ожидает значение длины (например, 10px, 2em, 50%). Это позволяет создавать плавные анимации между различными значениями длины.
• <number>: Ожидает числовое значение (например, 1, 3.14, -5). Полезно для анимации числовых свойств, таких как прозрачность или масштаб.
• <percentage>: Ожидает процентное значение (например, 25%, 100%).
• <color>: Ожидает значение цвета (например, #f00, rgb(255, 0, 0), hsl(0, 100%, 50%)). Позволяет создавать плавные цветовые переходы и анимации.
• <image>: Ожидает значение изображения (например, url(image.jpg), linear-gradient(...)).
• <integer>: Ожидает целочисленное значение (например, 1, -10, 0).
• <angle>: Ожидает значение угла (например, 45deg, 0.5rad, 200grad). Полезно для анимации вращений.
• <time>: Ожидает значение времени (например, 1s, 500ms). Полезно для управления длительностью или задержкой анимации через пользовательские свойства.
• <resolution>: Ожидает значение разрешения (например, 300dpi, 96dpi).
• <transform-list>: Ожидает список функций трансформации (например, translateX(10px) rotate(45deg)). Позволяет анимировать сложные трансформации.
• <custom-ident>: Ожидает пользовательский идентификатор (строку). Аналогично enum.
• <string>: Ожидает строковое значение (например, "Hello World"). Будьте осторожны с этим, так как анимация строк обычно не поддерживается.
• Пользовательские синтаксисы: Вы можете создавать более сложные синтаксисы, используя комбинации вышеупомянутых типов и операторов | (или), `[]` (группировка), `+` (один или более), `*` (ноль или более) и `?` (ноль или один). Например: <length> | <percentage> разрешает либо значение длины, либо процентное значение.

Выбор правильного syntax является ключевым для использования всей мощи @property.

Практические примеры @property

Давайте рассмотрим несколько практических примеров использования @property в вашем CSS.

Пример 1: Анимация цвета фона

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

@property --bg-color {
  syntax: '<color>';
  inherits: false;
  initial-value: #fff;
}

.button {
  background-color: var(--bg-color);
  transition: --bg-color 0.3s ease;
}

.button:hover {
  --bg-color: #f00; /* Красный */
}

В этом примере мы регистрируем пользовательское свойство --bg-color с синтаксисом <color>, что означает, что оно ожидает значение цвета. initial-value установлено на белый (#fff). При наведении на кнопку --bg-color изменяется на красный (#f00), и переход плавно анимирует изменение цвета фона.

Пример 2: Управление радиусом границы с помощью числа

Вы можете использовать @property для управления радиусом границы элемента и его анимации.

@property --border-radius {
  syntax: '<length>';
  inherits: false;
  initial-value: 0px;
}

.rounded-box {
  border-radius: var(--border-radius);
  transition: --border-radius 0.5s ease;
}

.rounded-box:hover {
  --border-radius: 20px;
}

Здесь мы регистрируем --border-radius как <length>, гарантируя, что оно принимает значения длины, такие как px, em или %. Начальное значение — 0px. При наведении на .rounded-box радиус границы анимируется до 20px.

Пример 3: Анимация смещения тени

Допустим, вы хотите анимировать горизонтальное смещение тени блока.

@property --shadow-offset-x {
  syntax: '<length>';
  inherits: false;
  initial-value: 0px;
}

.shadowed-box {
  box-shadow: var(--shadow-offset-x) 5px 10px rgba(0, 0, 0, 0.5);
  transition: --shadow-offset-x 0.3s ease;
}

.shadowed-box:hover {
  --shadow-offset-x: 10px;
}

В этом случае --shadow-offset-x зарегистрировано как <length>, и его начальное значение равно 0px. Свойство box-shadow использует это пользовательское свойство для своего горизонтального смещения. При наведении курсора смещение анимируется до 10px.

Пример 4: Использование <custom-ident> для создания тем

Синтаксис <custom-ident> позволяет вам определить набор предопределённых строковых значений, фактически создавая перечисление (enum) для ваших CSS-переменных. Это полезно для создания тем или управления различными состояниями.

@property --theme {
  syntax: '<custom-ident>';
  inherits: true;
  initial-value: light;
}

:root {
  --theme: light; /* Тема по умолчанию */
}

body {
  background-color: var(--theme) == light ? #fff : #333;
  color: var(--theme) == light ? #000 : #fff;
}

.dark-theme {
  --theme: dark;
}

Здесь --theme зарегистрировано с синтаксисом <custom-ident>. Хотя мы не перечисляем разрешённые идентификаторы непосредственно в правиле @property, код подразумевает, что это `light` и `dark`. Затем CSS использует условную логику (var(--theme) == light ? ... : ...) для применения разных стилей в зависимости от текущей темы. Добавление класса `dark-theme` к элементу переключит тему на тёмную. Обратите внимание, что условная логика с использованием `var()` не является стандартным CSS и часто требует препроцессоров или JavaScript. Более стандартный подход — использовать CSS-классы и каскадирование:

@property --theme {
  syntax: '<custom-ident>';
  inherits: true;
  initial-value: light;
}

:root {
  --theme: light;
}

body {
  background-color: #fff;
  color: #000;
}

body[data-theme="dark"] {
  background-color: #333;
  color: #fff;
}

/* JavaScript для переключения темы */
/* document.body.setAttribute('data-theme', 'dark'); */

В этом пересмотренном примере мы используем атрибут data-theme на элементе body для управления темой. JavaScript (закомментированный) будет использоваться для переключения атрибута между `light` и `dark`. Это более надёжный и стандартный подход к созданию тем с помощью CSS-переменных.

Преимущества использования @property

Использование @property даёт несколько преимуществ:

• Улучшенная читаемость и поддерживаемость кода: Явно определяя ожидаемый тип значения для пользовательского свойства, вы делаете свой код более понятным и менее подверженным ошибкам.
• Расширенные возможности анимации: @property позволяет создавать плавные переходы и анимации для пользовательских свойств, открывая новые возможности для создания динамичных и привлекательных пользовательских интерфейсов.
• Лучшая производительность: Браузеры могут оптимизировать отрисовку элементов, использующих зарегистрированные пользовательские свойства, что приводит к повышению производительности.
• Типобезопасность: Браузер проверяет, соответствует ли присвоенное значение объявленному синтаксису, предотвращая неожиданное поведение и облегчая отладку. Это особенно полезно в крупных проектах, где над кодовой базой работают много разработчиков.
• Значения по умолчанию: Гарантия того, что пользовательское свойство всегда имеет допустимое значение, даже если оно не задано явно, предотвращает ошибки и повышает надёжность вашего CSS.

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

На конец 2023 года @property имеет хорошую, но не универсальную поддержку браузерами. Он поддерживается в большинстве современных браузеров, включая Chrome, Firefox, Safari и Edge. Однако старые браузеры могут его не поддерживать. Всегда проверяйте актуальную информацию о совместимости на сайтах вроде Can I use... перед использованием @property в продакшене.

Для обработки старых браузеров вы можете использовать запросы возможностей (@supports), чтобы предоставить резервные стили:

@supports (--property: value) {
  /* Стили, использующие @property */
}

@supports not (--property: value) {
  /* Резервные стили для браузеров, не поддерживающих @property */
}

Замените --property и value на реальное пользовательское свойство и его значение.

Когда использовать @property

Рассмотрите возможность использования @property в следующих сценариях:

• Когда нужно анимировать пользовательские свойства: Это основной случай использования @property. Регистрация свойства с правильным синтаксисом позволяет создавать плавные анимации.
• Когда вы хотите обеспечить типобезопасность для пользовательских свойств: Если вы хотите гарантировать, что пользовательское свойство всегда будет содержать значение определённого типа, используйте @property для его регистрации.
• Когда вы хотите предоставить значение по умолчанию для пользовательского свойства: Дескриптор initial-value позволяет указать резервное значение.
• В крупных проектах: @property улучшает поддерживаемость кода и предотвращает ошибки, что делает его особенно полезным для больших проектов со множеством разработчиков.
• При создании переиспользуемых компонентов или дизайн-систем: @property может помочь обеспечить согласованность и предсказуемость ваших компонентов.

Частые ошибки, которых следует избегать

• Забыть дескриптор syntax: Без дескриптора syntax браузер не будет знать ожидаемый тип значения, и анимации не будут работать корректно.
• Использование неправильного значения syntax: Выбор неверного синтаксиса может привести к неожиданному поведению. Убедитесь, что вы выбрали синтаксис, который точно отражает ожидаемый тип значения.
• Отсутствие initial-value: Без начального значения пользовательское свойство может быть неопределённым, что приведёт к ошибкам. Всегда предоставляйте разумное значение по умолчанию.
• Чрезмерное использование * в качестве синтаксиса: Хотя это и удобно, использование * сводит на нет преимущества проверки типов и анимации. Используйте его только тогда, когда вам действительно нужно разрешить любой тип значения.
• Игнорирование совместимости с браузерами: Всегда проверяйте совместимость с браузерами и предоставляйте резервные стили для старых версий.

@property и CSS Houdini

@property является частью большего набора API под названием CSS Houdini. Houdini позволяет разработчикам подключаться к движку рендеринга браузера, предоставляя им беспрецедентный контроль над процессом стилизации и компоновки. Другие API Houdini включают:

• Paint API: Позволяет определять пользовательские фоновые изображения и границы.
• Animation Worklet API: Предоставляет способ создания высокопроизводительных анимаций, которые выполняются непосредственно в потоке композитора браузера.
• Layout API: Позволяет определять пользовательские алгоритмы компоновки.
• Parser API: Предоставляет доступ к CSS-парсеру браузера.

@property — это относительно простой для изучения API Houdini, но он открывает дверь к исследованию более продвинутых возможностей Houdini.

Заключение

@property — это мощное at-правило в CSS, которое открывает расширенные возможности для пользовательских свойств. Регистрируя пользовательские свойства в браузере, вы можете обеспечить типобезопасность, включить плавные анимации и повысить общую надёжность вашего CSS-кода. Хотя поддержка браузерами не является универсальной, преимущества использования @property, особенно в крупных проектах и дизайн-системах, делают его ценным инструментом для современной веб-разработки. Используйте @property и поднимите свои навыки CSS на новый уровень!