Интеграция с существующими проектами

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

Подключение FAST Element

Для начала необходимо установить библиотеку через npm:

npm install @microsoft/fast-element

После установки доступно несколько способов подключения:

  1. ES-модули в проекте на современном бандлере (Webpack, Vite, Rollup):
import { FASTElement, html, css } from "@microsoft/fast-element";
  1. Через CDN для быстрого прототипирования:
<script type="module">
  import { FASTElement, html, css } from "https://cdn.jsdelivr.net/npm/@microsoft/fast-element/dist/fast-element.min.js";
</script>

В проектах, где уже используется сборка через бандлер, предпочтителен первый способ, так как он поддерживает tree-shaking и уменьшает размер финального бандла.

Создание компонентов

FAST Element строится вокруг концепции классов, наследуемых от FASTElement, с описанием шаблона и стилей:

const template = html<MyComponent>`
  <div class="container">
    <span>${x => x.message}</span>
  </div>
`;

const styles = css`
  .container {
    padding: 10px;
    background-color: #f0f0f0;
  }
`;

export class MyComponent extends FASTElement {
  message = "Привет, FAST!";
}

FASTElement.define({ name: "my-component", template, styles, elementClass: MyComponent });

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

  • html — шаблон компонента с реактивными привязками.
  • css — инкапсулированные стили.
  • Свойства класса автоматически становятся реактивными, если используются в шаблоне.

Интеграция с существующим DOM

FAST компоненты полностью совместимы с обычным HTML. Их можно вставлять через стандартный DOM API или существующие фреймворки:

const container = document.getElementById("app");
const myComponent = document.createElement("my-component");
container.appendChild(myComponent);

Для проектов на React, Vue или Angular FAST компоненты могут использоваться как обычные веб-компоненты:

// React
function App() {
  return <my-component></my-component>;
}

Важно убедиться, что веб-компоненты зарегистрированы до рендера.

Реактивность и привязка данных

FAST Element поддерживает реактивные свойства и события:

export class CounterComponent extends FASTElement {
  count = 0;

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

const template = html<CounterComponent>`
  <button @click=${x => x.increment()}>Увеличить</button>
  <span>${x => x.count}</span>
`;

Привязка через ${x => x.property} автоматически обновляет DOM при изменении свойства.

Совет: Для интеграции с существующими данными можно использовать @observable из FAST, чтобы свойства реагировали на внешние изменения.

Стилизация и наследование CSS

FAST использует Shadow DOM по умолчанию, что обеспечивает изоляцию стилей. Для интеграции с глобальными стилями:

  • Использовать css переменные и кастомные свойства.
  • Включать глобальные стили через <style> в корневом документе.
  • Настраивать part и exportparts для внешней стилизации элементов внутри компонента:
const template = html`
  <div part="label">${x => x.label}</div>
`;

const styles = css`
  ::part(label) {
    color: red;
  }
`;

Совместная работа с другими библиотеками

FAST Element можно комбинировать с существующими библиотеками:

  • jQuery: манипуляции DOM ограничиваются корневыми элементами FAST.
  • React/Vue: использовать FAST как кастомные элементы, передав свойства через атрибуты.
  • State management (Redux, MobX): реактивные свойства можно синхронизировать с глобальным состоянием через подписки или прокси.

Ленивая загрузка компонентов

Для крупных проектов критически важно минимизировать начальный бандл. FAST поддерживает динамическую загрузку:

async function loadComponent() {
  const { MyComponent } = await import("./components/my-component.js");
  const element = document.createElement("my-component");
  document.body.appendChild(element);
}

loadComponent();

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

Взаимодействие с событиями

FAST Element использует стандартные DOM-события. Для передачи данных вверх по иерархии компонентов:

this.dispatchEvent(new CustomEvent("change", {
  detail: { value: this.value },
  bubbles: true,
  composed: true
}));

bubbles и composed обеспечивают распространение события за пределы Shadow DOM.

Миграция существующих UI-компонентов

Пошаговый подход:

  1. Выделить функциональность компонента в отдельный класс.
  2. Переписать шаблон на html FAST Element.
  3. Инкапсулировать стили через css.
  4. Зарегистрировать компонент с уникальным именем.
  5. Подменить старые DOM-узлы новыми компонентами постепенно.

Советы по интеграции

  • Использовать FASTElement.define() только один раз на компонент.
  • Проверять совместимость с Shadow DOM при работе с CSS-фреймворками.
  • Для больших проектов рекомендовано создавать библиотеку FAST-компонентов, чтобы централизовать поддержку и переиспользование.
Оглавление