Декоратор attr

Декоратор attr

Декоратор attr в FAST Element связывает публичное свойство компонента с атрибутом DOM, обеспечивая синхронное отражение значений между ними и позволяя настраивать преобразование типов. Использование attr избавляет от ручного чтения и записи атрибутов и упрощает реализацию реактивных свойств.

Декоратор применяется поверх поля класса. При инициализации компонента FAST создаёт соответствующий AttrController и настраивает наблюдение за изменениями атрибутов на элементе.

Пример базового применения:

import { FASTElement, attr, customElement } from '@microsoft/fast-element';

@customElement({ name: 'sample-counter', template: null })
class SampleCounter extends FASTElement {
  @attr count = 0;
}

В данном примере свойство count будет отражаться в атрибут count на DOM-элементе <sample-counter>, а его изменения будут автоматически обновлять состояние компонента.

Отражение и реактивность

attr делает свойство реактивным. Изменение значения приводит к обновлению шаблона и синхронизации с атрибутом. Это позволяет использовать свойства в биндингах и наблюдателях без дополнительных обёрток.

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

Настройка типа и преобразований

По умолчанию значения атрибутов рассматриваются как строки. Для типизации используются параметры декоратора. Доступные предустановленные типы: boolean, number, float, int. Например:

@attr({ mode: 'boolean' }) disabled: boolean;
@attr({ mode: 'int' }) page: number;

FAST автоматически преобразует строковое значение атрибута к указанному типу. Это избавляет от ручного парсинга и повышает надёжность.

Для нестандартных типов можно определить собственные преобразователи через converter:

@attr({
  converter: {
    toView: (value: string) => JSON.parse(value),
    fromView: (value: unknown) => JSON.stringify(value)
  }
})
data: any;

toView вызывается при чтении атрибута в свойство, fromView — при записи значения обратно в атрибут.

Контроль отражения в DOM

Иногда требуется хранить значение только на стороне свойства, не отражая его обратно в атрибут. Это решается опцией attribute: false:

@attr({ attribute: false })
internalState: number;

Свойство остаётся реактивным, но атрибут на DOM-элементе отсутствует, что полезно для внутренних данных компонента.

Переименование атрибутов

Имя атрибута можно переопределить, если оно должно отличаться от имени свойства:

@attr({ attribute: 'aria-label' })
label: string;

Переименование позволяет согласовать свойство с требованиями ARIA или внешних API без нарушения код-стиля.

Взаимодействие с шаблоном

Значения свойств, помеченных attr, используются в шаблонах через биндинги FAST. Изменения атрибутов, поступающие от пользователя или из фреймворков, автоматически отражаются в визуальном состоянии компонента. Это делает attr ключевым строительным элементом реактивности.

Отличия от обычных свойств

attr добавляет поверх стандартных свойств:

  • реактивное отслеживание изменений;
  • синхронизацию со значениями DOM;
  • кастомные преобразования типов;
  • интеграцию с жизненным циклом FAST.

Обычные свойства не участвуют в отражении и шаблонной реактивности, если не организовать это вручную.

Взаимодействие с жизненным циклом

Свойства, созданные с attr, инициализируются до вызова connectedCallback компонента. Это позволяет безопасно использовать их в ранних стадиях жизненного цикла. При изменениях FAST вызывает механизм наблюдения и обновляет привязки.

Частые сценарии использования

attr особенно полезен для:

  • состояний включено/выключено (boolean);
  • числовых параметров виджетов (page, count, min, max);
  • настроек ARIA и доступности (aria-*);
  • передачи структурированных данных с помощью собственных конвертеров;
  • синхронизации с внешними фреймворками через атрибуты HTML.

Особенности совместимости с HTML

attr ориентирован на естественный стиль HTML-атрибутов. Например, boolean-атрибуты не требуют присвоения значения: их наличие уже означает true. FAST корректно интерпретирует такие случаи и автоматически приводит значения к типу boolean.

Безопасность и производительность

Синхронизация атрибутов не требует MutationObserver пользователя. FAST применяет оптимизированный механизм наблюдения и холодного старта, минимизируя издержки на обновление состояния. Кэширование значений свойств исключает избыточные записи в DOM при идемпотентных изменениях.

Расширение и композиция

attr сочетается с другими механизмами FAST, включая observable, repeat, when и биндинги событий. Это обеспечивает гибкость при создании сложных UI-компонентов без дополнительной инфраструктуры.

Роль в архитектуре компонентов

Декоратор attr формирует контракт между компонентом и внешним окружением посредством HTML-атрибутов. Он позволяет описывать API компонента декларативно и типобезопасно, обеспечивая единообразие взаимодействия независимо от стека технологий, которые управляют DOM.

Оглавление