Перейти к содержанию

Жизненный цикл виджетов

WidgetLifecycle управляет ресурсами экземпляров виджетов в темах 4 поколения. Вызовите WidgetLifecycle.mount, чтобы запустить инициализацию для каждого корня и связать с ним DOM-обработчики, подписки EventBus и другие ресурсы.

API доступен как window.WidgetLifecycle после подключения версии common.v2.js с этим модулем. Подключение common.v2.js

Инициализация

В snippet.js виджета 4 поколения используйте предоставленный платформой селектор widget. Как устроен snippet.js

WidgetLifecycle.mount(widget, (element, lifecycle) => {
  const toggle = element.querySelector('[data-toggle-details]');
  toggle?.addEventListener('click', () => {
    element.classList.toggle('is-open');
  }, { signal: lifecycle.signal });

  const cartCount = element.querySelector('[data-cart-count]');
  if (cartCount) {
    EventBus.listen('update_items:insales:cart', cart => {
      cartCount.textContent = cart.items_count;
    }, { signal: lifecycle.signal });
  }
});

WidgetLifecycle.mount(targets, initialize) принимает CSS-селектор, один DOM-элемент или коллекцию элементов, например массив, NodeList, HTMLCollection или $widget. Метод фиксирует список до начала инициализации и передаёт каждый уникальный корень в initialize(element, lifecycle). element — нативный DOM-элемент. Новые корни, добавленные позже, инициализируйте отдельным вызовом mount.

Пустая выборка допустима. Некорректный селектор, null, коллекция с посторонним значением или отсутствие функции initialize приводят к исключению до запуска инициализации.

У каждого корня свой объект lifecycle. Повторный mount освобождает ресурсы предыдущего экземпляра перед новой инициализацией того же корня. Если у виджета есть независимые компоненты, передавайте в mount корень каждого компонента.

Функция initialize вызывается синхронно. Если она выбрасывает исключение, модуль очищает ресурсы этого экземпляра, выводит ошибку в консоль и продолжает инициализацию остальных корней. Асинхронные операции запускайте внутри initialize и обрабатывайте их ошибки самостоятельно. mount продолжает работу сразу после возврата из initialize, в том числе если функция вернула Promise.

Ресурсы экземпляра

Свойство или метод Назначение
lifecycle.signal Сигнал отмены для addEventListener, fetch и EventBus.listen.
lifecycle.onCleanup(fn) Регистрирует синхронную функцию очистки fn(element). Используйте для таймеров, обработчиков jQuery и библиотек с собственным методом очистки.
lifecycle.onCssChange(fn) Регистрирует обработчик быстрых CSS-настроек редактора.
lifecycle.destroy() Завершает работу одного экземпляра. Повторный вызов безопасен.
lifecycle.widgetItemId ID размещения на момент mount. В разметке виджета 4 поколения ID берётся из data-widget-drop-item-id у корня или ближайшего предка с этим атрибутом. Значение возвращается строкой, при отсутствии ID — null.

При уничтожении экземпляра модуль сначала отменяет сигнал, затем вызывает функции очистки в обратном порядке регистрации. Ошибка в одной функции выводится в консоль, остальные функции продолжают выполняться. После завершения уничтожения вызов onCleanup(fn) выполняет функцию сразу с аргументом null.

const unmount = WidgetLifecycle.mount(widget, (element, lifecycle) => {
  const timer = setInterval(() => {
    element.dataset.updatedAt = String(Date.now());
  }, 1000);

  lifecycle.onCleanup(() => clearInterval(timer));
});

// Вызовите перед удалением виджетов своим скриптом.
// unmount();

mount возвращает функцию unmount. Она завершает все ещё активные экземпляры этого вызова. Если корень уже повторно инициализирован, его новый экземпляр продолжит работу. На витрине для удаления виджета своим скриптом используйте unmount() или lifecycle.destroy().

Удаление и обновление в редакторе

В редакторе автоматическая очистка действует для корней внутри .editable-widget[data-widget-id] или .outside-widget[data-widget-id], включая саму обёртку. Модуль завершает работу экземпляра при удалении корня или его предка. Если корень успел вернуться в документ до обработки изменений DOM, экземпляр продолжит работу.

При замене HTML редактор публикует before_update_widget:insales:widgets перед выполнением нового JavaScript. Модуль очищает зарегистрированные экземпляры, чьи обёртки имеют соответствующий data-widget-id. Это может затронуть несколько размещений одного виджета. Сохраняйте в функциях очистки ссылки на ресурсы при их создании: к моменту очистки редактор уже мог заменить разметку.

Быстрые CSS-настройки

Редактор применяет быстрые CSS-настройки на месте. Если JavaScript виджета зависит от значения переменной, зарегистрируйте lifecycle.onCssChange(fn) внутри initialize. Функция получает ({ property }, element), где property — имя основной CSS-переменной. К этому моменту редактор уже применил значение и связанные переменные цвета.

При изменении настройки виджета обработчик вызывается у затронутого размещения. При изменении настройки темы он вызывается у всех активных экземпляров, зарегистрировавших обработчик в редакторе. При уничтожении экземпляра подписка снимается автоматически.

WidgetLifecycle.mount(widget, (element, lifecycle) => {
  function syncGap() {
    element.dataset.gap = getComputedStyle(element).getPropertyValue('--gap').trim();
  }

  syncGap();
  lifecycle.onCssChange(({ property }) => {
    if (property === '--gap') syncGap();
  });
});