Структура файлов библиотеки

Для начала работы с Locomotive Scroll необходимо установить библиотеку через npm или подключить её напрямую через CDN. В случае npm используется команда:

npm install locomotive-scroll

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

import LocomotiveScroll from 'locomotive-scroll';

При подключении через CDN достаточно добавить ссылку на скрипт в HTML:

<script src="https://cdn.jsdelivr.net/npm/locomotive-scroll/dist/locomotive-scroll.min.js"></script>

Также необходимо подключить CSS стили библиотеки:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/locomotive-scroll/dist/locomotive-scroll.css" />

Основные файлы библиотеки

Locomotive Scroll содержит несколько ключевых файлов, которые формируют её функциональность:

  1. locomotive-scroll.js – основной JavaScript-файл библиотеки. Содержит весь код для инициализации скролла, обработку событий, плавную прокрутку и работу с анимациями. Этот файл необходимо импортировать для работы функционала библиотеки.

  2. locomotive-scroll.min.js – минифицированная версия основного скрипта. Она содержит тот же функционал, но сжатый для ускорения загрузки страницы.

  3. locomotive-scroll.css – стили, обеспечивающие корректное отображение скролла и поддержку эффекта параллакса. Этот файл отвечает за overflow, smooth scrolling и работу внутренних обёрток элементов.

  4. helpers.js (в исходной структуре исходников) – вспомогательные функции для расчёта положения элементов, оптимизации производительности и работы с событиями resize/scroll. Этот файл редко используется напрямую, но критически важен для работы основной логики.

  5. es/ и dist/ – папки с разными вариантами сборки:

    • es/ содержит ES-модули для современных сборщиков, таких как Webpack или Vite.
    • dist/ – готовые сборки для подключения напрямую в браузере, включая минифицированные версии.

  6. types/ – папка с TypeScript-типами. Она позволяет использовать библиотеку в TypeScript-проектах с полной типизацией.

Структура проекта с использованием Locomotive Scroll

Правильная организация файлов и папок проекта обеспечивает стабильную работу и удобство масштабирования. Типичная структура может выглядеть так:

project/
│
├─ src/
│  ├─ js/
│  │  └─ main.js
│  ├─ scss/
│  │  └─ styles.scss
│  └─ index.html
│
├─ node_modules/
│  └─ locomotive-scroll/
│      ├─ dist/
│      ├─ es/
│      ├─ src/
│      └─ types/
│
└─ package.json
  • src/js/main.js – инициализация и настройка Locomotive Scroll.
  • node_modules/locomotive-scroll/ – директория с библиотекой и её исходными файлами.
  • dist/ – готовые сборки библиотеки для подключения через тег <script>.

Инициализация и ключевые опции

Для работы Locomotive Scroll необходимо создать новый объект и передать конфигурацию:

const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true,
  direction: 'vertical',
  multiplier: 1,
  class: 'is-reveal'
});

Ключевые параметры:

  • el – контейнер с прокручиваемым контентом, обязателен.
  • smooth – включает плавную прокрутку.
  • direction – направление скролла (vertical или horizontal).
  • multiplier – коэффициент скорости прокрутки.
  • class – CSS-класс, который добавляется элементам при появлении в зоне видимости.

Связь JavaScript и CSS файлов

Locomotive Scroll работает через комбинацию JS и CSS. CSS отвечает за overflow контейнера и скрытие стандартного скролла, а JS обрабатывает движение содержимого и события. Без подключения CSS эффекта плавного скролла не будет, даже если скрипт инициализирован.

Основные зависимости:

  1. Контейнер должен иметь CSS свойство:
[data-scroll-container] {
  overflow: hidden;
}
  1. Элементы, которые должны анимироваться, получают атрибут data-scroll:
<div data-scroll data-scroll-speed="2">Параллакс элемент</div>

Минимизация и сборка

Для продакшена рекомендуется использовать минифицированный скрипт (locomotive-scroll.min.js) и объединять его с собственными JS-файлами через сборщик. В исходной структуре библиотеки есть как ES-модули (es/), так и CommonJS-сборки, что облегчает интеграцию с различными проектами.

Использование TypeScript

Файлы из types/ позволяют корректно типизировать объект Locomotive Scroll:

import LocomotiveScroll, { LocomotiveScrollOptions } from 'locomotive-scroll';

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

const scroll = new LocomotiveScroll(options);

Это обеспечивает автодополнение, проверку типов и предотвращает ошибки при передаче конфигурации.

Внутренние зависимости

Locomotive Scroll не требует внешних библиотек для базовой работы, но использует несколько вспомогательных утилит внутри:

  • RAF (requestAnimationFrame) для плавной анимации.
  • Event listeners для resize и scroll.
  • Intersection Observer для отслеживания появления элементов на экране.

Эти модули находятся в исходниках библиотеки, но не требуют отдельного подключения пользователем.

Оглавление