Декораторы

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

Декоратор `@customElement`

Декоратор @customElement регистрирует класс как кастомный элемент и связывает его с определённым именем в DOM. Он автоматически создает конструктор и связывает компонент с шаблоном.

import { FASTElement, html, css, customElement } from "@microsoft/fast-element";

const template = html`
  
    ${x => x.message}
  
`;

const styles = css`
  p {
    color: blue;
  }
`;

@customElement({ name: "my-component", template, styles })
class MyComponent extends FASTElement {
  message = "Привет, FAST!";
}

Особенности:

name — обязательное поле, определяет имя тега.
template — связывает HTML-шаблон с компонентом.
styles — подключает CSS напрямую к компоненту.
Автоматически создаётся shadow DOM, если это предусмотрено настройками шаблона.

Декоратор `@attr`

@attr используется для создания атрибутов HTML, которые синхронизируются со свойствами класса. Это ключевой инструмент для реактивности и двусторонней привязки.

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

class MyComponent extends FASTElement {
  @attr title;        // тип string по умолчанию
  @attr({ mode: "boolean" }) disabled; // логический атрибут
}

Параметры @attr:

mode — определяет тип атрибута: "string", "boolean", "number".
attribute — позволяет задать другое имя атрибута в DOM.
Автоматически происходит синхронизация значения свойства и атрибута, включая конвертацию типов.

Пример работы boolean-атрибута:

Если в DOM присутствует disabled, свойство disabled в классе будет true. При его изменении на false атрибут автоматически удаляется.

Декоратор `@observable`

@observable используется для создания реактивного свойства, которое автоматически инициирует перерисовку компонента при изменении значения. В отличие от @attr, оно не связано с HTML-атрибутом, а управляет только внутренним состоянием.

import { FASTElement, observable } from "@microsoft/fast-element";

class Counter extends FASTElement {
  @observable count = 0;

  increment() {
    this.count++;
  }
}

Особенности:

Позволяет привязывать свойства в шаблоне: ${x => x.count}.
Поддерживает подписки на изменения через propertyChanged:

countChanged(oldValue, newValue) {
  console.log(`count изменился с ${oldValue} на ${newValue}`);
}

Именование метода Changed автоматически вызывается при каждом изменении.

Декоратор `@watch`

@watch позволяет следить за изменениями нескольких свойств или сложных зависимостей. Он более гибкий, чем propertyChanged.

import { FASTElement, observable, watch } from "@microsoft/fast-element";

class PersonComponent extends FASTElement {
  @observable firstName = "";
  @observable lastName = "";

  @watch("firstName,lastName")
  fullNameChanged() {
    console.log(`Полное имя: ${this.firstName} ${this.lastName}`);
  }
}

Особенности:

Можно указывать несколько свойств через запятую.
Метод вызывается при любом изменении указанных свойств.
Используется для объединённых вычислений или побочных эффектов.

Декоратор `@ref`

@ref позволяет сохранять ссылку на DOM-элемент внутри компонента для прямого доступа.

import { FASTElement, ref, html } from "@microsoft/fast-element";

const template = html`
  
  
`;

class MyComponent extends FASTElement {
  inputElement;

  focusInput() {
    this.inputElement.focus();
  }
}

Особенности:

Сохраняет прямую ссылку на элемент в свойство класса.
Позволяет манипулировать элементом без поиска через querySelector.
Работает только внутри шаблона, переданного через html.