Декоратор customElement

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

Регистрация пользовательского элемента

Синтаксис customElement выглядит следующим образом:

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

@customElement({
  name: "my-element",
  template: html`<p>Hello, FAST!</p>`,
  styles: css`
    p {
      color: blue;
      font-weight: bold;
    }
  `
})
class MyElement extends FASTElement {}

Ключевые моменты:

  • name – уникальное имя тега, которое будет использоваться в HTML (my-element). Обязательное свойство.
  • template – определяет внутреннюю структуру элемента с помощью шаблона FAST, поддерживает реактивные привязки.
  • styles – CSS, применяемый только к данному компоненту, изолированный от внешнего окружения.

После применения декоратора элемент автоматически регистрируется в браузере через customElements.define.

Использование шаблонов

Шаблоны FAST Element создаются с помощью функции html, которая поддерживает динамическую привязку к свойствам класса. Например:

const template = html<MyElement>`
  <p>${x => x.message}</p>
`;
  • x => x.message — функция, привязывающая значение свойства message к содержимому параграфа.
  • Поддерживаются условные блоки, циклы и слоты, что позволяет создавать сложные интерфейсы без прямого манипулирования DOM.

Применение стилей

Стили задаются через css:

import { css } from "@microsoft/fast-element";

const styles = css`
  p {
    font-size: 16px;
    color: red;
  }
`;
  • CSS изолируется на уровне Shadow DOM, что предотвращает конфликты с глобальными стилями.
  • Можно использовать переменные CSS для динамических тем и цветовых схем.

Декоратор customElement и реактивные свойства

FAST Element автоматически отслеживает изменения свойств и обновляет шаблон:

@customElement({
  name: "user-card",
  template: html<UserCard>`<h1>${x => x.name}</h1>`
})
class UserCard extends FASTElement {
  name = "Иван";
}
  • Изменение свойства name вызовет автоматический рендер без необходимости вручную обновлять DOM.
  • Декоратор работает совместно с механизмом реактивности observable, который можно использовать для сложных зависимостей.
import { observable } from "@microsoft/fast-element";

class UserCard extends FASTElement {
  @observable name = "Иван";
}

Параметры декоратора

customElement поддерживает несколько опций:

  • name – имя тега.
  • template – шаблон компонента.
  • styles – CSS стили.
  • shadowOptions – настройки Shadow DOM (например, { mode: 'open' }).

Пример:

@customElement({
  name: "fancy-button",
  template: html`<button>${x => x.label}</button>`,
  styles: css`button { background: gold; }`,
  shadowOptions: { mode: "open" }
})
class FancyButton extends FASTElement {
  label = "Click me";
}

Расширение существующих элементов

Можно использовать customElement для создания элементов, расширяющих стандартные HTML-теги:

@customElement({
  name: "fancy-input",
  template: html`<input type="text" value="${x => x.value}" />`,
  shadowOptions: { mode: "open" }
})
class FancyInput extends FASTElement {
  value = "Hello";
}
  • Класс наследует функциональность FAST Element, но сохраняет семантику базового элемента.
  • Shadow DOM позволяет полностью изолировать стили, сохраняя при этом стандартные возможности HTML.

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

Декоратор можно комбинировать с функциями для динамического создания компонентов:

function createCustomElement(name, template, styles) {
  @customElement({ name, template, styles })
  class DynamicElement extends FASTElement {}
  return DynamicElement;
}

const AlertBox = createCustomElement(
  "alert-box",
  html`<div>${x => x.message}</div>`,
  css`div { color: red; }`
);
  • Позволяет создавать библиотеки компонентов с минимальным дублированием кода.
  • Упрощает генерацию элементов на основе данных или конфигураций.

Особенности использования

  • Декоратор работает только с классами, наследующими FASTElement.
  • Регистрация компонента автоматически делает его доступным в DOM.
  • Если элемент с таким именем уже зарегистрирован, будет выброшена ошибка.

Декоратор customElement в FAST Element обеспечивает простой, но мощный механизм создания реактивных веб-компонентов с изолированными стилями и поддержкой шаблонов. Комбинация с observable, Shadow DOM и функциями шаблонов позволяет строить масштабируемые интерфейсы без сложной ручной работы с DOM.

Оглавление