Изменения в API

Waypoints — это библиотека для отслеживания скроллинга и выполнения определённых действий при достижении элементов на странице. В новых версиях библиотеки произошли ключевые изменения в API, которые напрямую влияют на способ инициализации, настройки и использования точек контроля. Рассмотрим их подробно.

Инициализация Waypoints

Ранее инициализация происходила с использованием конструктора new Waypoint({}) и указанием element и handler. В новых версиях API добавлена поддержка массивов элементов и возможность использовать селекторы напрямую:

const waypoint = new Waypoint({
  element: document.querySelector('.section'),
  handler: function(direction) {
    console.log('Scrolled to waypoint!', direction);
  },
  offset: '50%' // теперь может быть строкой или числом
});

Ключевые изменения:

  • offset теперь поддерживает строковые значения, например '50%', 'bottom-in-view' и т.д., что упрощает позиционирование.
  • handler принимает один параметр — direction, который может быть 'down' или 'up'.

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

document.querySelectorAll('.section').forEach(el => {
  new Waypoint({
    element: el,
    handler: function(dir) {
      console.log(el.id, 'scrolled', dir);
    }
  });
});

Контроль направления скролла

В старом API для контроля направления использовались условные проверки внутри обработчика. Новое API предоставляет прямой параметр direction и методы enable() и disable() для управления поведением:

const wp = new Waypoint({
  element: document.querySelector('#target'),
  handler: function(direction) {
    if (direction === 'down') {
      console.log('Пользователь скроллит вниз');
    } else {
      console.log('Пользователь скроллит вверх');
    }
  }
});

wp.disable(); // временно отключить waypoint
wp.enable();  // включить обратно

Новые опции offset и контекст

Offset определяет, на какой позиции элемента срабатывать waypoint. В старой версии использовались только числовые значения. В новой версии добавлены:

  • Процент от высоты окна ('25%')
  • Ключевые позиции ('bottom-in-view', 'top-in-view')
  • Произвольная функция, возвращающая число:
const wp = new Waypoint({
  element: document.querySelector('#dynamic'),
  handler: function() { console.log('Waypoint сработал'); },
  offset: function() {
    return window.innerHeight / 2;
  }
});

Context позволяет отслеживать скроллинг не всего окна, а конкретного контейнера:

new Waypoint({
  element: document.querySelector('.inner'),
  handler: function(dir) { console.log('scroll in container', dir); },
  context: document.querySelector('.scrollable-container')
});

Sticky Elements и Waypoints

Для реализации “липких” элементов (sticky) Waypoints теперь поддерживает нативную интеграцию через метод sticky. Это упрощает добавление фиксированных элементов с динамическим смещением:

const sticky = new Waypoint.Sticky({
  element: document.querySelector('.navbar'),
  stuckClass: 'is-stuck',  // класс добавляется при срабатывании
  offset: 0
});

Изменения по сравнению со старым API:

  • Класс stuckClass полностью настраиваемый
  • Автоматическая обработка высоты родительского контейнера
  • Возможность динамически отключать и включать sticky через destroy() и refresh()

Методы обновления и удаления

API добавляет новые методы для динамических интерфейсов:

  • refresh() — пересчитывает позицию всех waypoint-ов, особенно полезно при изменении DOM.
  • destroy() — полностью удаляет waypoint, освобождая память и удаляя обработчики событий.

Пример:

const wp = new Waypoint({
  element: document.querySelector('.dynamic'),
  handler: function(dir) { console.log('Waypoint сработал'); }
});

// После изменения DOM
wp.refresh();

// Когда waypoint больше не нужен
wp.destroy();

Поддержка событий через Waypoints.Events

Новая версия API предоставляет глобальный объект событий для отслеживания всех waypoint-ов на странице:

Waypoints.Events.on('waypoint.reached', function(event) {
  console.log('Waypoint достигнут:', event.element, event.direction);
});

События включают:

  • waypoint.reached — waypoint сработал
  • waypoint.destroyed — waypoint удалён
  • waypoint.refresh — waypoint пересчитан

Это упрощает централизованное логирование и реакцию на множество элементов одновременно.

Совместимость и миграция

Основные точки внимания при переходе на новую версию:

  1. Параметры offset — проверять поддержку строковых и функциональных значений.
  2. Контекст скролла — старый API использовал scrollContext, новый — context.
  3. Sticky — интеграция теперь через Waypoint.Sticky, старые плагины могут конфликтовать.
  4. Методы управления — enable(), disable(), destroy(), refresh() заменяют старые подходы с прямым манипулированием событиями.

Эти изменения делают Waypoints более гибким, позволяют легко работать с динамическим контентом и сложными интерфейсами, а также упрощают управление скроллом и “липкими” элементами.

Оглавление