Миграция с версии 3 на 4

Waypoints 4 существенно отличается от версии 3, прежде всего архитектурой и способами инициализации точек. В версии 4 отказались от jQuery-зависимости, что повлияло на синтаксис создания точек и работу с событиями. Основные изменения включают:

  • Инициализация через конструктор: В версии 4 Waypoint создаётся напрямую через new Waypoint({...}), вместо использования метода $.waypoint():
// Версия 3
$('#element').waypoint({
  handler: function(direction) {
    console.log(direction);
  }
});

// Версия 4
var waypoint = new Waypoint({
  element: document.getElementById('element'),
  handler: function(direction) {
    console.log(direction);
  }
});

  • События теперь обрабатываются через опцию handler, а не через jQuery-события типа .on('waypoint').

  • Контейнер (context) задаётся явно через опцию context. Если не указать, по умолчанию используется window.

Параметры конструктора Waypoint 4

  • element — DOM-элемент, для которого создаётся точка.
  • handler(direction) — функция, вызываемая при пересечении точки. Параметр direction принимает значения "down" или "up".
  • offset — расстояние в пикселях или процент от начала контейнера, на котором срабатывает waypoint. Например, offset: '50%' срабатывает в середине видимой области.
  • context — контейнер, который отслеживает прокрутку. Обычно window.
  • enabled — флаг, разрешающий или запрещающий waypoint. Можно включать и отключать динамически.
  • group — логическая группа waypoint’ов для синхронного срабатывания.

Пример использования всех ключевых опций:

var waypoint = new Waypoint({
  element: document.getElementById('section1'),
  handler: function(direction) {
    console.log('Появление section1, направление:', direction);
  },
  offset: '25%',
  context: document.getElementById('scroll-container'),
  enabled: true,
  group: 'sections'
});

Работа с offset

В версии 4 offset можно задавать как пиксели, проценты или функции:

// Пиксели
offset: 100

// Процент от высоты контейнера
offset: '50%'

// Функция
offset: function() {
  return this.element.clientHeight / 2;
}

Важно: функция offset вызывается в момент скролла и позволяет динамически менять позицию срабатывания waypoint.

Динамическое управление waypoint

Waypoints 4 предоставляет методы для включения, отключения и уничтожения точек:

waypoint.disable(); // Отключить
waypoint.enable();  // Включить
waypoint.destroy(); // Уничтожить

Это особенно полезно при адаптивной верстке или при динамическом создании элементов на странице.

Группы и синхронизация

Группы позволяют управлять множественными waypoint одновременно. Каждой точке можно задать group, а затем вызвать срабатывание всех waypoint’ов группы:

var waypoint1 = new Waypoint({
  element: document.getElementById('section1'),
  handler: function() {},
  group: 'sections'
});

var waypoint2 = new Waypoint({
  element: document.getElementById('section2'),
  handler: function() {},
  group: 'sections'
});

// Все точки группы можно сбросить или вызвать обработку
Waypoint.Group.findOrCreate({name: 'sections'}).flush();

Метод flush() используется для немедленного срабатывания всех waypoint’ов в группе в зависимости от текущей позиции скролла.

Миграция событий

В версии 3 часто использовались jQuery-события:

$('#element').on('waypoint.reached', function(direction) {
  console.log(direction);
});

В версии 4 это заменяется прямым вызовом handler при инициализации:

var waypoint = new Waypoint({
  element: document.getElementById('element'),
  handler: function(direction) {
    console.log(direction);
  }
});

Если требуется делегирование или множественные обработчики, создаются несколько waypoint’ов с разными handler или используется группировка.

Контекст скролла

В версии 4 контекст задаётся явно. Это позволяет отслеживать скролл внутри блоков:

var container = document.getElementById('scrollable-container');

var waypoint = new Waypoint({
  element: document.getElementById('target'),
  handler: function(direction) { console.log(direction); },
  context: container
});

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

Поддержка адаптивной верстки

В Waypoints 4 добавлен механизм пересчёта координат при изменении размеров окна:

window.addEventListener('resize', function() {
  Waypoint.refreshAll();
});

Это важно для корректного срабатывания waypoint при динамическом изменении размеров элементов или окна браузера.

Отличия работы с infinite scroll

Реализация бесконечной прокрутки в версии 4 также изменилась. Вместо jQuery-событий используется явная проверка и вызов handler при добавлении новых элементов:

var infiniteWaypoint = new Waypoint.Infinite({
  element: document.getElementById('container')
});

Теперь при добавлении нового контента достаточно вызвать Waypoint.refreshAll(), чтобы новые точки начали отслеживаться.

Основные шаги миграции

  1. Заменить $.waypoint() на new Waypoint({}).
  2. Переписать обработчики с jQuery-событий на handler.
  3. Указать context, если скролл отслеживается не по window.
  4. Проверить все offset и заменить функции/проценты при необходимости.
  5. Использовать методы disable(), enable(), destroy() вместо прямого управления через jQuery.
  6. Для группового управления использовать group и Waypoint.Group.flush().
  7. Добавить Waypoint.refreshAll() при динамическом изменении DOM или ресайзе окна.

Эти шаги обеспечивают корректную работу всех существующих точек и позволяют использовать новые возможности версии 4 без потери функционала.

Оглавление