Обновление с версии 3 на 4

При обновлении Locomotive Scroll с версии 3 до версии 4 произошли значительные изменения в архитектуре и API, которые напрямую влияют на инициализацию, работу с событиями и настройки скроллинга. Основное отличие — переход от глобального объекта к модульной структуре с явным импортом, что улучшает Tree Shaking и совместимость с современными сборщиками вроде Webpack и Vite.

Пример импорта в версии 4:

import LocomotiveScroll from 'locomotive-scroll';

Ранее в версии 3 часто использовался глобальный объект window.LocomotiveScroll, что усложняло контроль за загрузкой и зависимостями.

Инициализация скролла

В версии 4 инициализация требует указания контейнера и нескольких ключевых опций:

const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true,
  direction: 'vertical',
  multiplier: 1.0,
  smartphone: {
    smooth: true
  },
  tablet: {
    smooth: true
  }
});

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

  • el — контейнер скролла. Важно, чтобы он был единственным элементом, внутри которого происходит весь скроллинг.
  • smooth — включает плавный скролл.
  • direction — направление скролла: 'vertical' или 'horizontal'.
  • multiplier — коэффициент скорости прокрутки.
  • Настройки для мобильных устройств теперь разделены по типу устройства (smartphone, tablet).

Работа с событиями

Версия 4 полностью переработала систему событий. Методы on и off остались, но изменился формат передачи аргументов. Основные события:

  • scroll — срабатывает при скролле, передает объект с текущей позицией.
  • call — позволяет слушать кастомные триггеры на элементах с data-scroll-call.
  • resize — срабатывает при изменении размеров контейнера.

Пример использования события scroll:

scroll.on('scroll', (args) => {
  console.log(args.scroll.y); // текущая вертикальная позиция
  console.log(args.scroll.direction); // направление прокрутки
});

Атрибуты элементов

В версии 4 изменились названия и структура data-атрибутов для элементов с анимацией:

Версия 3 Версия 4 Комментарий
data-scroll-speed data-scroll-speed Осталось без изменений
data-scroll-offset data-scroll-offset Теперь поддерживает массив [top, bottom]
data-scroll-call data-scroll-call Используется с событиями call

Важно отметить, что теперь анимации лучше работают с IntersectionObserver, что снижает нагрузку на основной поток.

Проблемы совместимости и исправления

  1. Инициализация до загрузки DOM В версии 4 LocomotiveScroll нельзя инициализировать до полной загрузки контейнера. Рекомендуется использовать:

    window.addEventListener('DOMContentLoaded', () => {
  const scroll = new LocomotiveScroll({ el: document.querySelector('[data-scroll-container]'), smooth: true });
});

  2. Плавный скролл на мобильных устройствах В версии 4 плавный скролл на iOS и Android стал более стабильным, но требуется явная настройка smartphone.smooth и tablet.smooth.

  3. Методы обновления Ранее использовался update(), теперь рекомендуется scroll.update() после изменения DOM:

    scroll.update();

  4. Удаление скролла Метод destroy() очищает события и сбрасывает стили контейнера:

    scroll.destroy();

Адаптация кастомных эффектов

Если в версии 3 использовались кастомные параллакс-эффекты через transform: translateY(), в версии 4 рекомендуется использовать встроенные опции data-scroll-speed и data-scroll-direction. Для сложных эффектов можно подключать сторонние анимационные библиотеки вроде GSAP совместно с событиями scroll или call.

Пример параллакса с GSAP:

scroll.on('scroll', ({ scroll }) => {
  gsap.to('.parallax', {
    y: scroll.y * 0.3,
    ease: 'power1.out'
  });
});

Оптимизация производительности

Версия 4 уделяет больше внимания производительности:

  • События throttling/debouncing встроены в ядро.
  • Поддержка IntersectionObserver уменьшает количество просчетов при анимациях элементов.
  • Меньше стилей через JS — рекомендуется использовать CSS для transform и opacity.
Оглавление