Создание экземпляра Locomotive Scroll

Для начала работы с Locomotive Scroll необходимо подключить библиотеку к проекту. Существует два основных способа:

Через npm:

npm install locomotive-scroll

После установки в проект можно импортировать библиотеку:

import LocomotiveScroll from 'locomotive-scroll';
import 'locomotive-scroll/dist/locomotive-scroll.css';

Через CDN:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/locomotive-scroll@4.2.1/dist/locomotive-scroll.min.css">
<script src="https://cdn.jsdelivr.net/npm/locomotive-scroll@4.2.1/dist/locomotive-scroll.min.js"></script>

Использование CDN удобно для быстрого прототипирования или небольших проектов без сборщика модулей.

Инициализация экземпляра

Создание экземпляра Locomotive Scroll выполняется с помощью конструктора new LocomotiveScroll(options). Основной объект принимает один обязательный параметр — объект конфигурации options.

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

Основные параметры

  • el — DOM-элемент, который будет использоваться как контейнер для скролла. Обычно это элемент с атрибутом data-scroll-container.
  • smooth — логическое значение. Включает плавный скролл.
  • direction — направление скролла ('vertical' по умолчанию или 'horizontal').
  • lerp — скорость сглаживания, число от 0 до 1. Чем меньше значение, тем более «тяжелый» и медленный скролл.
  • reloadOnContextChange — автоматически обновляет экземпляр при изменении DOM (например, при SPA навигации).

Пример с настройкой скорости и горизонтального скролла:

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

Атрибуты для элементов внутри контейнера

Для использования эффектов, анимаций и управления элементами внутри контейнера скролла, Locomotive Scroll опирается на data-атрибуты:

  • data-scroll — активирует элемент для скролл-слежения.
  • data-scroll-speed — задает скорость движения элемента относительно основного скролла.
  • data-scroll-delay — задержка движения элемента.
  • data-scroll-position — позиционирование элемента: 'top', 'bottom', 'center'.
  • data-scroll-repeat — позволяет элементу повторять анимацию при повторном скролле.

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

<div data-scroll data-scroll-speed="2">
  Элемент движется быстрее основного скролла
</div>

Методы экземпляра

Locomotive Scroll предоставляет множество методов для управления поведением скролла:

  • update() — пересчитывает позиции элементов. Используется после динамического изменения DOM.
  • scrollTo(target, options) — прокручивает контейнер к указанной цели. target может быть числом, селектором или элементом. options включают скорость, задержку и направление.
scroll.scrollTo('#section2', { offset: 0, duration: 1500, easing: [0.25, 0.0, 0.35, 1.0] });
  • start() и stop() — управление скроллом, можно временно приостанавливать или запускать его.
  • destroy() — удаляет экземпляр и возвращает DOM в исходное состояние.

События экземпляра

Locomotive Scroll поддерживает прослушивание событий:

  • scroll — срабатывает при каждом движении скролла.
  • call — срабатывает на элементах с атрибутом data-scroll-call.
  • resize — при изменении размеров окна.

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

scroll.on('scroll', (obj) => {
  console.log('Текущая позиция скролла:', obj.scroll.y);
});

scroll.on('call', (value, way, obj) => {
  console.log('Вызван элемент с call:', value, 'Направление:', way);
});

Адаптация под динамический контент

Если на странице происходит динамическое добавление контента (например, через AJAX или SPA-роутинг), необходимо вызывать метод update():

scroll.update();

Это гарантирует корректное отслеживание всех элементов и правильное позиционирование анимаций.

Особенности работы с мобильными устройствами

  • smooth часто отключают на мобильных устройствах из-за производительности. Можно использовать условное определение:
const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: window.innerWidth > 768,
});
  • На iOS важно учитывать поведение overflow: hidden и -webkit-overflow-scrolling. Locomotive Scroll автоматически применяет оптимизации для плавного скролла.

Практический пример полной инициализации

import LocomotiveScroll from 'locomotive-scroll';
import 'locomotive-scroll/dist/locomotive-scroll.css';

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

scroll.on('scroll', (obj) => {
  console.log('Позиция Y:', obj.scroll.y);
});

В этом примере создается экземпляр, учитывающий разные устройства, с плавной прокруткой и возможностью отслеживать текущее положение скролла.

Оглавление