Установка и подключение

Библиотека Waypoints распространяется в виде JavaScript-файлов и может быть установлена через популярные менеджеры пакетов.

Через npm:

npm install waypoints

Через yarn:

yarn add waypoints

После установки библиотека становится доступной для подключения в проекте через систему модулей.

Подключение в ES-модулях:

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

Для использования адаптера с jQuery:

import 'waypoints/lib/jquery.waypoints';

Важно учитывать, что структура пакета включает несколько вариантов сборки:

noframework.waypoints — для чистого JavaScript
jquery.waypoints — для работы с jQuery
дополнительные утилиты и расширения (например, shortcuts)

Подключение через CDN

При отсутствии сборщика модулей библиотеку удобно подключать напрямую через CDN.

Базовая версия (без фреймворков):

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

Версия для jQuery:

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

Если используется jQuery, порядок подключения строго определён:

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="path/to/jquery.waypoints.min.js"></script>

Нарушение порядка приведёт к ошибкам, так как Waypoints расширяет объект jQuery.

Структура файлов библиотеки

После установки доступны следующие ключевые файлы:

waypoints.js — основной файл
noframework.waypoints.js — версия без зависимостей
jquery.waypoints.js — адаптер для jQuery
shortcuts/ — дополнительные утилиты (например, inview, sticky)

Каждый файл решает отдельную задачу, и выбор зависит от архитектуры проекта.

Выбор версии подключения

Чистый JavaScript (без зависимостей):

минимальный размер
отсутствие сторонних библиотек
полный контроль над DOM

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

С использованием jQuery:

более простой синтаксис
интеграция с существующим кодом на jQuery

import 'waypoints/lib/jquery.waypoints';

Проверка корректности подключения

После подключения библиотеки важно убедиться, что она доступна в окружении.

Для vanilla JS:

console.log(typeof Waypoint); // должен вернуть "function"

Для jQuery:

console.log(typeof $.fn.waypoint); // должен вернуть "function"

Если возвращается undefined, возможны следующие причины:

неверный путь к файлу
ошибка в порядке подключения скриптов
конфликт версий

Подключение в сборщиках (Webpack, Vite, Rollup)

При использовании современных инструментов сборки важно учитывать особенности импорта.

Webpack / Vite:

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

new Waypoint({
  element: document.getElementById('target'),
  handler: function(direction) {
    console.log('Scrolled to waypoint!');
  }
});

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

библиотека не использует default export в классическом виде
иногда требуется явное указание пути к файлу
tree-shaking не применяется, так как библиотека не модульная

Подключение расширений (Shortcuts)

Waypoints включает набор дополнительных модулей, расширяющих функциональность.

Пример подключения inview:

<script src="path/to/noframework.waypoints.min.js"></script>
<script src="path/to/shortcuts/inview.min.js"></script>

Пример через npm:

import 'waypoints/lib/noframework.waypoints';
import 'waypoints/lib/shortcuts/inview';

Расширения подключаются после основного файла и зависят от него.

Типичные ошибки при установке

1. Неправильный путь к файлу

<script src="waypoints.js"></script> <!-- файл отсутствует -->

2. Отсутствие зависимости (для jQuery-версии)

<script src="jquery.waypoints.min.js"></script> <!-- без jQuery -->

3. Использование ES-модулей без сборщика

import Waypoint from 'waypoints'; // не работает в браузере без сборки

4. Конфликт версий jQuery

старая версия jQuery может не поддерживать Waypoints 4.x

Минимальный рабочий пример подключения

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

<div id="box" style="margin-top: 1000px;">Target</div>

<script>
  new Waypoint({
    element: document.getElementById('box'),
    handler: function() {
      console.log('Waypoint triggered');
    }
  });
</script>

</body>
</html>

Организация подключения в проекте

Рекомендуемая структура:

project/
│
├── src/
│   ├── js/
│   │   ├── main.js
│   │   └── waypoints-init.js
│
├── node_modules/
│
└── dist/

Пример инициализации в отдельном файле:

// waypoints-init.js
import Waypoint from 'waypoints/lib/noframework.waypoints';

export function initWaypoints() {
  new Waypoint({
    element: document.querySelector('.section'),
    handler: function() {
      console.log('Section reached');
    }
  });
}