Параметры событий

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

События генерируются объектами Controller и Scene. Основная работа ведётся со сценами, поскольку именно они описывают поведение элементов при прокрутке.

Общий синтаксис обработки событий

Для подписки на событие используется метод .on():

scene.on("eventName", function(event) {
    // обработка события
});

Удаление обработчика осуществляется через .off():

scene.off("eventName", callback);

Также доступна одноразовая подписка через .once().

Объект события (event object)

Каждое событие передаёт в обработчик объект event, содержащий набор параметров, описывающих текущее состояние сцены. Эти параметры являются ключевыми для построения логики.

Основные свойства:

  • type — имя события
  • target — сцена, вызвавшая событие
  • progress — текущий прогресс сцены (от 0 до 1)
  • state — текущее состояние сцены
  • scrollDirection — направление прокрутки
  • scrollPos — текущая позиция прокрутки

Параметр type

Определяет тип произошедшего события.

Примеры значений:

  • enter
  • leave
  • start
  • end
  • progress
  • update

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

scene.on("enter leave", function(event) {
    console.log(event.type);
});

Параметр target

Содержит ссылку на сцену, вызвавшую событие. Позволяет обращаться к методам сцены внутри обработчика.

scene.on("enter", function(event) {
    console.log(event.target === scene); // true
});

Параметр progress

Отражает степень выполнения сцены. Значение находится в диапазоне от 0 до 1.

  • 0 — сцена ещё не началась
  • 1 — сцена полностью завершена

Применяется для синхронизации анимаций:

scene.on("progress", function(event) {
    console.log(event.progress);
});

Часто используется совместно с анимационными библиотеками, например GSAP.

Параметр state

Описывает текущее состояние сцены. Возможные значения:

  • BEFORE — сцена ещё не достигнута
  • DURING — сцена активна
  • AFTER — сцена завершена

Пример:

scene.on("enter leave", function(event) {
    console.log(event.state);
});

Это удобно для управления логикой отображения элементов.

Параметр scrollDirection

Показывает направление прокрутки:

  • FORWARD — вниз
  • REVERSE — вверх
  • PAUSED — без движения
scene.on("update", function(event) {
    console.log(event.scrollDirection);
});

Полезно для создания адаптивных анимаций, зависящих от направления скролла.

Параметр scrollPos

Содержит текущее значение прокрутки в пикселях относительно документа.

scene.on("update", function(event) {
    console.log(event.scrollPos);
});

Позволяет синхронизировать поведение сцены с другими элементами страницы.

Дополнительные параметры событий

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

startPos и endPos

Определяют позиции начала и конца сцены:

scene.on("update", function(event) {
    console.log(event.startPos, event.endPos);
});

Используются для анализа диапазона действия сцены.

Событие enter

Срабатывает, когда сцена становится активной.

scene.on("enter", function(event) {
    console.log("Сцена активирована");
});

Параметры:

  • scrollDirection
  • state

Событие leave

Срабатывает при выходе из сцены.

scene.on("leave", function(event) {
    console.log("Сцена завершена");
});

Событие progress

Вызывается при изменении прогресса сцены.

scene.on("progress", function(event) {
    console.log(event.progress);
});

Часто используется для:

  • параллакса
  • анимации по скроллу
  • управления таймлайнами

Событие update

Срабатывает при каждом обновлении позиции прокрутки.

scene.on("update", function(event) {
    console.log(event.scrollPos);
});

Отличается высокой частотой вызова, поэтому требует оптимизации обработчиков.

События start и end

  • start — достижение начальной точки сцены
  • end — достижение конечной точки
scene.on("start end", function(event) {
    console.log(event.type);
});

Комбинирование событий

ScrollMagic позволяет подписываться сразу на несколько событий:

scene.on("enter leave progress", function(event) {
    console.log(event.type, event.progress);
});

Это упрощает централизованную обработку логики.

Практическое применение параметров событий

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

scene.on("enter", function(event) {
    document.querySelector(".box").classList.add("active");
});

scene.on("leave", function(event) {
    document.querySelector(".box").classList.remove("active");
});

Синхронизация с анимацией

scene.on("progress", function(event) {
    animation.progress(event.progress);
});

Реакция на направление скролла

scene.on("update", function(event) {
    if (event.scrollDirection === "FORWARD") {
        console.log("Вниз");
    } else {
        console.log("Вверх");
    }
});

Оптимизация работы с событиями

Высокочастотные события (progress, update) могут создавать нагрузку. Рекомендуется:

  • использовать debounce/throttle
  • избегать тяжёлых вычислений
  • минимизировать работу с DOM

Пример throttle:

let lastCall = 0;

scene.on("update", function(event) {
    let now = Date.now();
    if (now - lastCall > 100) {
        console.log(event.scrollPos);
        lastCall = now;
    }
});

Особенности работы событий

  • События вызываются в строгом порядке (например: enter → start → progress)
  • При прокрутке вверх порядок меняется (leave → end)
  • Одно действие пользователя может вызвать несколько событий

Отладка событий

Для визуального контроля используется плагин:

scene.addIndicators();

Он добавляет маркеры начала и конца сцены.

Итоговая структура события

Пример полного объекта:

{
    type: "progress",
    target: scene,
    progress: 0.5,
    state: "DURING",
    scrollDirection: "FORWARD",
    scrollPos: 350,
    startPos: 200,
    endPos: 600
}

Такой набор параметров делает систему событий ScrollMagic мощным инструментом для точного контроля поведения интерфейса при прокрутке.

Оглавление