Обратная совместимость

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

Поддержка старых браузеров

FAST Element строится на стандартах Custom Elements и Shadow DOM, которые поддерживаются в современных браузерах. Для обеспечения обратной совместимости с браузерами, где эти технологии не реализованы, используются полифиллы.

  • @webcomponents/webcomponentsjs — основной набор полифиллов для Custom Elements и Shadow DOM.
  • Важно подключать полифиллы до загрузки компонентов, чтобы не возникало ошибок при регистрации кастомных элементов.

Пример подключения полифиллов через npm:

import '@webcomponents/webcomponentsjs/webcomponents-bundle.js';
import { FASTElement, html, css } from '@microsoft/fast-element';

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

Для обратной совместимости с предыдущими версиями компонентов нужно использовать стабильные имена тегов. Резкое изменение имени кастомного элемента приведёт к необходимости менять весь существующий код.

class MyButton extends FASTElement {
  // определение свойств и методов
}

customElements.define('my-button', MyButton);
  • Поддержание существующих атрибутов и свойств критично: добавление новых свойств допустимо, но удаление старых может сломать интеграции.
  • Свойства, которые раньше были строками, не рекомендуется менять на объекты или массивы без сохранения совместимого способа чтения.

Обработка свойств и атрибутов

FAST Element использует реактивные свойства через @observable и @attr. Для обратной совместимости:

  • Не менять типы существующих свойств. Если требуется расширение, добавлять новые свойства с уникальными именами.
  • Для атрибутов, которые могут содержать разные типы данных, следует использовать методы сериализации и десериализации.

Пример:

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

export class MyComponent extends FASTElement {
  @attr({ mode: 'fromView', converter: { 
      fromView: (v) => v.split(','), 
      toView: (v) => v.join(',') 
  }})
  items;
}

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

Поддержка событий

Изменения в событиях компонентов должны быть обратносогласованными.

  • Старые события не удаляются, а если меняется их поведение, сохраняется старый формат с пометкой deprecated.
  • Новые события добавляются с уникальными именами, чтобы не ломать существующие обработчики.

Пример:

this.$emit('value-changed', { oldValue, newValue });
// Для обратной совместимости сохраняем старое событие
this.$emit('change', { oldValue, newValue });

Миграция компонентов

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

  • Полифиллы и шимы для новых API, которые отсутствуют в старых браузерах.
  • Временные мосты для старых атрибутов и событий.
  • Разделение новой функциональности в отдельные свойства или методы, чтобы старый код продолжал работать без изменений.

Совместимость с CSS

FAST Element использует CSS Shadow Parts для стилизации частей компонента. Чтобы сохранить совместимость:

  • Старые селекторы должны работать через классические CSS-пути.
  • Новые стили можно добавлять через part или CSS Custom Properties, не изменяя существующие классы и структуры DOM.

Пример использования CSS Shadow Parts:

my-button::part(base) {
  background-color: blue;
}

my-button::part(label) {
  font-weight: bold;
}

Автотесты и проверка обратной совместимости

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

  • Unit-тесты для проверки старых свойств, методов и событий.
  • End-to-end тесты для проверки интеграции с существующими страницами.
  • Автоматическая проверка на регрессию API, чтобы новые версии не ломали старый функционал.

Использование Fast Element в сочетании с тщательным тестированием и полифиллами позволяет создавать современные веб-компоненты, которые остаются стабильными и совместимыми с существующими проектами.

Оглавление