Интеграция с legacy-кодом

SkateJS — библиотека для создания веб-компонентов, ориентированная на модульность и переиспользуемость. Одной из ключевых задач при внедрении SkateJS в существующие проекты является интеграция с legacy-кодом, написанным на чистом JavaScript, jQuery или других устаревших фреймворках. Рассмотрим основные подходы и тонкости, обеспечивающие плавное сосуществование новых компонентов с существующей архитектурой.

Подключение SkateJS к существующей странице

Для использования SkateJS в старом проекте достаточно подключить библиотеку через <script>:

<script type="module">
  import { define, component, props } from 'skatejs';
</script>

Важно учитывать:

  • SkateJS работает через ES-модули, поэтому в legacy-коде может потребоваться полифилл для поддержки import.
  • Компоненты SkateJS регистрируются через функцию define, что гарантирует их совместимость с нативными веб-компонентами.
  • Если проект использует сборщик типа Webpack или Parcel, необходимо убедиться, что ES-модули корректно транслируются в совместимый формат для браузеров.

Создание SkateJS-компонента для legacy-разметки

Компоненты SkateJS можно внедрять в существующую разметку без полной переделки:

import { define, component, props } from 'skatejs';

const LegacyButton = component({
  tag: 'legacy-button',
  props: {
    label: props.string
  },
  render(elem) {
    elem.textContent = this.label;
  }
});

define(LegacyButton);

После этого <legacy-button label="Нажми меня"></legacy-button> можно вставить в любой участок старой страницы.

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

  • Свойства компонента можно связывать с существующими JS-объектами.
  • SkateJS автоматически отслеживает изменения свойств через props и обновляет DOM.
  • Поддержка атрибутов HTML позволяет интегрировать компонент без изменения существующих скриптов.

Работа с событиями и legacy-JS

SkateJS использует CustomEvent для передачи событий, что позволяет легко связывать компоненты с legacy-кодом:

elem.addEventListener('click', () => {
  const event = new CustomEvent('legacy-action', { detail: { value: 42 } });
  elem.dispatchEvent(event);
});

// В legacy-коде
document.querySelector('legacy-button').addEventListener('legacy-action', e => {
  console.log(e.detail.value);
});

Рекомендации:

  • Для совместимости с jQuery можно использовать .on() вместо addEventListener.
  • События компонента должны быть названы уникально, чтобы избежать конфликтов с существующими скриптами.
  • SkateJS поддерживает как делегирование, так и прямую привязку событий.

Инкапсуляция стилей и взаимодействие с legacy-CSS

SkateJS применяет Shadow DOM по умолчанию через свой рендерер, что защищает стили компонента от глобальных CSS. Для интеграции с legacy-проектом доступны два подхода:

  1. Shadow DOM с адаптацией CSS:
import { h, component } from 'skatejs';

const StyledComponent = component({
  tag: 'styled-component',
  render(elem) {
    return <div class="legacy-style">Контент</div>;
  }
});
  • В этом случае можно добавить класс, совместимый с существующими стилями, и подключить его через глобальный CSS.
  1. Отказ от Shadow DOM:
const NonShadow = component({
  tag: 'non-shadow',
  shadow: false,
  render(elem) {
    elem.textContent = 'Встроенный компонент';
  }
});
  • Позволяет полностью использовать существующие CSS-правила без ограничения видимости.
  • Рекомендуется для проектов, где глобальная стилизация уже сложная и масштабная.

Интеграция с jQuery и другими библиотеками

SkateJS-компоненты можно использовать совместно с jQuery:

$('legacy-button').on('click', function() {
  $(this).trigger('legacy-action', { value: 100 });
});

Особенности взаимодействия:

  • SkateJS не конфликтует с jQuery, если события правильно делегированы.
  • Методы jQuery можно вызывать на элементах SkateJS, но нужно учитывать Shadow DOM: прямой доступ к внутренним элементам потребует shadowRoot.querySelector(...).
  • Для упрощения можно использовать shadow: false при интеграции с библиотеками, ожидающими обычный DOM.

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

Часто legacy-приложения управляют состоянием через глобальные объекты или события. SkateJS позволяет связывать свойства компонента с внешними данными:

const state = { count: 0 };

const Counter = component({
  tag: 'counter-component',
  props: {
    count: props.number
  },
  render(elem) {
    elem.textContent = `Счёт: ${this.count}`;
  }
});

define(Counter);

// Обновление из legacy-кода
setInterval(() => {
  state.count += 1;
  document.querySelector('counter-component').count = state.count;
}, 1000);
  • SkateJS автоматически реагирует на изменения props.
  • Можно создавать двухстороннюю привязку с существующим глобальным состоянием без пересмотра всей архитектуры.

Миграция отдельных модулей на SkateJS

При постепенной интеграции важно:

  1. Начинать с независимых компонентов, минимально затрагивающих legacy-код.
  2. Использовать CustomEvent и props для связи с существующими скриптами.
  3. Выбирать подход к стилям: Shadow DOM для изоляции или глобальные стили для совместимости.
  4. Обеспечивать совместимость с сборщиками и полифилами ES-модулей.

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

Оглавление