Подключение к проекту

ScrollMagic — это мощная библиотека для создания анимаций и управления событиями при скролле страницы. Для её использования требуется корректное подключение как самой библиотеки, так и необходимых зависимостей, а также понимание структуры проекта.

Установка через CDN

Самый быстрый способ подключить ScrollMagic — использование CDN. Это позволяет сразу начать работу без установки через пакетный менеджер. Необходимые скрипты можно подключить в <head> или перед закрывающим тегом </body>:

<!-- ScrollMagic core -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/ScrollMagic/2.0.8/ScrollMagic.min.js"></script>

<!-- Плагин для анимаций с GreenSock (GSAP) -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/ScrollMagic/2.0.8/plugins/animation.gsap.min.js"></script>

<!-- Плагин для отладки (optional) -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/ScrollMagic/2.0.8/plugins/debug.addIndicators.min.js"></script>

Ключевые моменты при подключении через CDN:

  • ScrollMagic.min.js — основной функционал библиотеки.
  • animation.gsap.min.js — связывает ScrollMagic с библиотекой GSAP, что позволяет создавать плавные анимации.
  • debug.addIndicators.min.js — визуальные индикаторы триггеров для отладки сцен.

Установка через npm / yarn

Для современных проектов удобнее использовать менеджеры пакетов:

npm install scrollmagic
# или
yarn add scrollmagic

После установки подключение в JavaScript выглядит следующим образом:

import ScrollMagic from "scrollmagic";
import "scrollmagic/scrollmagic/uncompressed/plugins/animation.gsap";
import "scrollmagic/scrollmagic/uncompressed/plugins/debug.addIndicators";

Использование модульного подхода позволяет интегрировать библиотеку в сборщики вроде Webpack или Vite и уменьшить вес конечного бандла за счет tree-shaking.

Подключение стилей и элементов

ScrollMagic не требует собственных CSS-файлов, однако для корректной работы сцен важно, чтобы элементы, к которым будут применяться триггеры и анимации, имели определённые размеры и позиционирование. Например:

.section {
  height: 100vh;
  position: relative;
}
.box {
  width: 100px;
  height: 100px;
  background-color: #3498db;
  position: absolute;
  top: 0;
  left: 50%;
  transform: translateX(-50%);
}

Совет: при работе с динамическими сценами рекомендуется заранее задавать высоту контейнеров, иначе ScrollMagic может некорректно рассчитывать положение триггеров.

Инициализация контроллера

ScrollMagic использует контроллер (ScrollMagic.Controller) для управления всеми сценами. Создание контроллера — первый шаг после подключения библиотеки:

const controller = new ScrollMagic.Controller();

Контроллер может принимать опции:

  • container — кастомный контейнер скролла (по умолчанию window).
  • vertical — направление скролла (true по умолчанию).
  • globalSceneOptions — общие настройки для всех сцен (например, triggerHook, duration).

Пример с глобальными опциями:

const controller = new ScrollMagic.Controller({
  globalSceneOptions: {
    triggerHook: 0.8
  }
});

Создание первой сцены

После подключения ScrollMagic и инициализации контроллера можно создавать сцены:

const scene = new ScrollMagic.Scene({
  triggerElement: ".section", // элемент-триггер
  duration: 200, // длина сцены в пикселях
  triggerHook: 0.5 // позиция триггера на экране
})
.setClassToggle(".box", "visible") // добавление класса при скролле
.addTo(controller); // добавление сцены в контроллер

Особенности:

  • triggerElement — элемент, который запускает сцену.
  • duration — длина сцены, определяющая продолжительность анимации при скролле.
  • triggerHook — положение триггера на экране (0 — верх, 1 — низ).
  • setClassToggle — стандартный метод для изменения состояния элементов.

Интеграция с GSAP

Для более сложных анимаций используется GSAP вместе с ScrollMagic:

const tween = gsap.to(".box", { y: 300, duration: 1 });

const scene = new ScrollMagic.Scene({
  triggerElement: ".section",
  duration: 500
})
.setTween(tween)
.addIndicators({ name: "box move" })
.addTo(controller);

В этом примере объект .box будет плавно перемещаться на 300px по оси Y в течение прокрутки длиной 500px. Плагин addIndicators добавляет визуальные маркеры для отладки сцен.

Подключение к SPA и динамическим страницам

В проектах на фреймворках типа Vue, React или Angular ScrollMagic подключается аналогично, но с учётом динамического DOM:

  • Инициализация контроллера и сцен должна происходить после того, как элементы появятся в DOM.
  • Для повторного использования контроллеров можно сохранять их в глобальном состоянии или использовать хук жизненного цикла компонента.
  • После удаления компонентов рекомендуется уничтожать сцены через scene.destroy() и controller.destroy() для предотвращения утечек памяти.

Настройка и оптимизация

  • Минимизировать количество сцен на странице для повышения производительности.
  • Использовать lazy load для тяжелых анимаций.
  • При работе с мобильными устройствами учитывать высоту экрана и адаптивные триггерные позиции.
  • Для плавной работы при интенсивном скролле рекомендуется включать requestAnimationFrame внутри GSAP-анимаций.

Подключение ScrollMagic с соблюдением этих принципов обеспечивает стабильную работу анимаций и корректное управление сценами независимо от структуры проекта.

Оглавление