Полный список методов API

Для работы с библиотекой создается объект Headroom, которому передается DOM-элемент шапки страницы (header) и объект с настройками:

const header = document.querySelector("header");
const headroom = new Headroom(header, {
  tolerance: 5,
  offset: 50,
  classes: {
    initial: "headroom",
    pinned: "headroom--pinned",
    unpinned: "headroom--unpinned",
    top: "headroom--top",
    notTop: "headroom--not-top",
    bottom: "headroom--bottom",
    notBottom: "headroom--not-bottom",
  }
});
headroom.init();

Параметры настройки:

  • tolerance — чувствительность к прокрутке. Может быть числом или объектом { up, down }.
  • offset — смещение в пикселях перед активацией поведения.
  • classes — объект с CSS-классами, которые применяются в зависимости от состояния шапки.

Методы экземпляра Headroom.js

init()

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

headroom.init();

destroy()

Удаляет все слушатели событий и CSS-классы, возвращая элемент в исходное состояние.

headroom.destroy();

Используется для динамического удаления поведения шапки, например, при смене маршрута в SPA.

pin()

Принудительное закрепление шапки в видимой позиции. Добавляет класс pinned и снимает unpinned.

headroom.pin();

Полезно, если требуется временно зафиксировать шапку при определенном действии пользователя.

unpin()

Принудительное скрытие шапки при скролле. Добавляет класс unpinned и снимает pinned.

headroom.unpin();

Используется для управления шапкой через события вне стандартного скролла.

toggle()

Переключает состояние шапки между pinned и unpinned в зависимости от текущего состояния.

headroom.toggle();

Подходит для сценариев с программной анимацией интерфейса.

update()

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

headroom.update({
  tolerance: { up: 10, down: 5 },
  offset: 100
});

Можно использовать при динамическом изменении параметров прокрутки или классов CSS.

Свойства экземпляра

  • element — DOM-элемент, к которому применен Headroom.
  • classes — объект текущих CSS-классов.
  • initialised — флаг, указывающий, была ли инициализация.

Пример доступа:

console.log(headroom.element); // <header>
console.log(headroom.initialised); // true

Callback-функции

Headroom.js поддерживает несколько событий, которые можно определить при создании экземпляра:

  • onPin — вызывается при закреплении шапки.
  • onUnpin — вызывается при скрытии шапки.
  • onTop — вызывается, когда шапка находится в начале страницы.
  • onNotTop — вызывается при выходе шапки из верхней позиции.
  • onBottom — вызывается при достижении низа страницы.
  • onNotBottom — вызывается при уходе шапки от низа страницы.

Пример использования:

const headroom = new Headroom(header, {
  onPin: () => console.log("Шапка закреплена"),
  onUnpin: () => console.log("Шапка скрыта"),
  onTop: () => console.log("Верх страницы"),
  onNotTop: () => console.log("Страница прокручена вниз")
});
headroom.init();

Полезные трюки с API

  1. Динамическое изменение offset: можно пересчитать поведение шапки при изменении размеров окна:
window.addEventListener("resize", () => {
  headroom.update({ offset: window.innerHeight / 10 });
});

  1. Комбинация методов pin/unpin с событиями: можно интегрировать с другими скриптами интерфейса для плавного скрытия/появления шапки.

  2. Доступ к текущему состоянию через CSS-классы:

if (header.classList.contains("headroom--unpinned")) {
  console.log("Шапка скрыта");
}

Расширенные возможности

  • Расширение классов CSS: можно добавлять кастомные состояния через объект classes.
  • Интеграция с SPA: вызовы destroy() и повторный init() помогают адаптировать поведение шапки при динамическом изменении DOM.
  • Адаптивность под touch-устройства: Headroom.js корректно обрабатывает скролл на мобильных устройствах, что позволяет комбинировать методы API с событиями свайпа.

Headroom.js предоставляет полный контроль над поведением шапки, позволяя управлять состояниями через методы pin, unpin, toggle, update и слушать ключевые события через callback-функции. Свойства экземпляра обеспечивают доступ к DOM-элементу и текущему состоянию, что делает библиотеку гибкой и легко интегрируемой в сложные интерфейсы.

Оглавление