Синтаксис и базовая структура

Для использования Waypoints в проекте необходимо подключить саму библиотеку. Наиболее распространённые варианты: подключение через CDN или локальный файл. Пример подключения через CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/waypoints/4.0.1/noframework.waypoints.min.js"></script>

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

npm install waypoints

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

import Waypoint from 'waypoints/lib/noframework.waypoints';

Создание базового Waypoint

Waypoint создаётся с помощью конструктора Waypoint, который принимает объект конфигурации. Основная структура выглядит так:

var waypoint = new Waypoint({
  element: document.getElementById('target-element'),
  handler: function(direction) {
    console.log('Waypoint достигнут! Направление:', direction);
  },
  offset: '50%' 
});

Ключевые параметры конструктора:

  • element – HTML-элемент, на котором устанавливается waypoint. Это обязательный параметр.
  • handler – функция-обработчик, вызываемая при достижении элемента. Принимает аргумент direction, который может быть 'down' или 'up'.
  • offset – смещение от верхней границы окна, при котором срабатывает waypoint. Может быть задано в пикселях (100) или в процентах ('50%'). Значение по умолчанию — 0.

Направление срабатывания

Аргумент direction в handler показывает, как пользователь прокручивает страницу относительно элемента:

  • 'down' – прокрутка вниз, когда элемент появляется на экране.
  • 'up' – прокрутка вверх, когда элемент возвращается в область видимости.

Пример условного срабатывания:

var waypoint = new Waypoint({
  element: document.getElementById('section1'),
  handler: function(direction) {
    if (direction === 'down') {
      console.log('Пользователь скроллит вниз к section1');
    } else {
      console.log('Пользователь скроллит вверх к section1');
    }
  },
  offset: '75%'
});

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

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

  • Конкретное число пикселей:
offset: 200 // сработает, когда верх элемента будет на 200px от верха окна
  • Процент от высоты окна:
offset: '50%' // сработает, когда верх элемента достигнет середины окна
  • Функция для динамического расчёта:
offset: function() {
  return window.innerHeight * 0.3;
}

Уничтожение и повторное создание Waypoints

Waypoint можно удалить с помощью метода destroy, что важно для оптимизации и динамических страниц:

waypoint.destroy();

Для динамических элементов часто используется комбинация destroy и создания нового waypoint после изменения DOM.

Группы и контексты

Waypoints можно организовывать в группы и контексты:

  • Группа позволяет управлять несколькими waypoint одновременно. Пример:
Waypoint.Group.findByName('my-group').disable();
Waypoint.Group.findByName('my-group').enable();
  • Контекст определяет область скролла. По умолчанию — window, но можно задать свой контейнер:
var waypoint = new Waypoint({
  element: document.getElementById('item'),
  handler: function() { console.log('Сработало в кастомном контейнере'); },
  context: document.getElementById('scroll-container')
});

Настройка горизонтального скролла

Waypoints поддерживают горизонтальный скролл через модуль Horizontal:

var horizontalWaypoint = new Waypoint({
  element: document.getElementById('horizontal-item'),
  handler: function(direction) {
    console.log('Горизонтальный waypoint:', direction);
  },
  horizontal: true,
  offset: '25%'
});

Параметр horizontal: true переключает отслеживание с вертикального на горизонтальное.

Основные события и методы

Waypoints предоставляет несколько полезных методов:

  • enable() — активирует waypoint.
  • disable() — деактивирует waypoint, чтобы он больше не срабатывал.
  • destroy() — полностью удаляет waypoint и освобождает ресурсы.
  • trigger(direction) — принудительно вызывает handler с заданным направлением.

Пример программного вызова:

waypoint.trigger('down'); // срабатывает так, как будто пользователь прокрутил вниз

Резюме структуры

Базовый шаблон Waypoint:

var waypoint = new Waypoint({
  element: HTML_ELEMENT,          // обязательный
  handler: function(direction) {}, // обязательный
  offset: 'процент или px',       // необязательный, по умолчанию 0
  context: SCROLL_CONTAINER,      // необязательный, по умолчанию window
  horizontal: true/false,          // необязательный, по умолчанию false
  enabled: true,                  // необязательный, true по умолчанию
  group: 'GROUP_NAME'             // необязательный, для группировки
});

Эта структура обеспечивает полную управляемость waypoint и позволяет гибко интегрировать его в любую веб-страницу.

Оглавление