Различия версий 3.x и 4.x

Архитектура и установка

В версии 3.x Locomotive Scroll использует традиционный подход с созданием экземпляра через конструктор:

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

Версия 4.x изменила структуру экспорта и теперь библиотека поставляется в модульном формате с поддержкой ES Modules. Импорт осуществляется напрямую:

import LocomotiveScroll from 'locomotive-scroll';

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

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

  • Поддержка модульной структуры облегчает интеграцию с современными сборщиками (Webpack, Vite, Parcel).
  • Поддержка разных платформ (smartphone, tablet) стала нативной, в 3.x приходилось использовать сторонние методы или кастомные медиа-запросы.

Управление скроллом

В версии 3.x методы управления прокруткой были ограничены:

scroll.scrollTo('#section');
scroll.update();

В версии 4.x появилась расширенная API:

  • scroll.scrollTo(target, options) теперь поддерживает кастомные easing-функции, offset и duration.
  • Метод scroll.start() и scroll.stop() позволяют полностью включать или останавливать управление прокруткой.
  • Добавлены события жизненного цикла: call, scroll, scrollStart, scrollStop, что облегчает синхронизацию анимаций с прокруткой.

Пример с кастомным easing:

scroll.scrollTo('#section', {
  offset: -100,
  duration: 1500,
  easing: [0.25, 0.0, 0.35, 1.0]
});

Smooth Scroll и производительность

Версия 4.x оптимизирует плавность скролла за счет использования requestAnimationFrame и улучшенной виртуализации. Отличия:

  • В 3.x плавность могла «тормозить» на тяжелых страницах из-за использования CSS transforms без оптимизации.
  • В 4.x добавлен механизм debounce и throttle событий, что снижает нагрузку на main-thread.
  • Поддержка GPU-ускорения через will-change: transform применяется автоматически, уменьшает джиттер на старых устройствах.

Параллакс и элементы с данными

Модель работы с data-scroll и data-scroll-speed в 4.x стала более гибкой:

  • Поддержка отрицательных значений скорости и кастомных классов анимации.
  • Возможность задавать отдельные параметры для планшетов и мобильных через атрибуты:
<div data-scroll data-scroll-speed="2" data-scroll-mobile-speed="1.5">
  Контент
</div>
  • Встроенная система call-бэков позволяет отслеживать элементы при появлении на экране без использования IntersectionObserver вручную.

Обработка событий и интеграция с GSAP

Версия 4.x упрощает интеграцию с анимационными библиотеками, особенно с GSAP:

import { gsap } from "gsap";

scroll.on("scroll", (instance) => {
  gsap.to(".box", {
    y: instance.scroll.y * 0.3,
    ease: "power3.out"
  });
});

Преимущества:

  • В 3.x требовалось вручную синхронизировать позиции через scroll.instance.scroll.y.
  • В 4.x прокрутка возвращает объект с актуальной позицией и возможностью получения смещения для конкретного элемента.
  • Возможность одновременной анимации нескольких элементов без потери производительности.

Учет адаптивности

В версии 4.x введены встроенные настройки для адаптивного скролла:

const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true,
  smartphone: { smooth: false },
  tablet: { smooth: true }
});
  • Позволяет отключать или включать плавность на определенных устройствах без дополнительных проверок window.innerWidth.
  • В 3.x адаптивность приходилось реализовывать через медиа-запросы и ручное уничтожение/создание экземпляра scroll.

API уничтожения и пересоздания

Версия 4.x улучшила методы destroy и init:

scroll.destroy();
scroll.init();
  • Метод destroy() очищает все слушатели событий и возвращает DOM к исходному состоянию.
  • Позволяет безопасно пересоздавать экземпляр скролла при динамическом изменении DOM.
  • В 3.x destroy был менее надежным, часто оставлял стили transform и слушатели, что приводило к багам.

Итоговая таблица сравнений

Функция / Свойство 3.x 4.x
Импорт Через <script> или CommonJS ES Modules
Плавный скролл Основной CSS transform requestAnimationFrame + GPU оптимизация
Адаптивность Кастомные методы Встроенные smartphone и tablet
Callbacks Ограниченные Расширенные с жизненным циклом
Параллакс элементы Только data-scroll-speed data-scroll-speed, data-scroll-mobile-speed, call-бэки
Управление скроллом Ограниченное scrollTo, start, stop, кастомные easing
Интеграция с GSAP Требует синхронизации вручную Прямая через события scroll
Destroy / init Частично Полностью безопасное восстановление DOM

Версия 4.x Locomotive Scroll ориентирована на современный фронтенд, улучшает производительность, расширяет API и упрощает адаптивность, что делает её предпочтительной для новых проектов по сравнению с 3.x.

Оглавление