Breaking changes между версиями

Headroom.js — это легковесная библиотека для управления поведением элементов интерфейса при прокрутке страницы, в первую очередь для «прилипающих» шапок (header). Развитие библиотеки сопровождалось рядом breaking changes, которые важно учитывать при обновлении между версиями. Основные изменения касаются структуры и инициализации, API событий и конфигурационных опций.

Изменения в инициализации

В ранних версиях (0.x и ранние 1.x) инициализация Headroom.js выполнялась через прямой вызов конструктора с элементом и опциями:

var header = document.querySelector("#header");
var headroom = new Headroom(header, {
  tolerance: 5,
  offset: 100,
  classes: {
    pinned: "header--pinned",
    unpinned: "header--unpinned"
  }
});
headroom.init();

В версии 0.12+ была введена поддержка инициализации через data-атрибуты и новый метод Headroom.attach, что позволило уменьшить boilerplate-код. Старый способ остался рабочим, но рекомендуется мигрировать на более современные вызовы.

Изменения в опциях конфигурации

tolerance

  • До версии 0.10: tolerance принимал одно числовое значение, определявшее порог для обнаружения прокрутки.
  • Начиная с версии 0.12: tolerance может быть объектом с ключами up и down, что позволяет задавать отдельные пороги для прокрутки вверх и вниз:
tolerance: {
  up: 10,
  down: 5
}

Это изменение важно, поскольку старый синтаксис {tolerance: 5} теперь интерпретируется иначе, и поведение header может отличаться.

offset

  • Ранее offset мог быть только числом.
  • В версиях 0.12+ offset можно задавать как функцию, возвращающую динамическое значение, что особенно полезно для адаптивного интерфейса:
offset: function() {
  return window.innerHeight / 2;
}

Изменения в классах CSS

Headroom.js использует CSS-классы для управления состояниями header:

  • headroom--pinned
  • headroom--unpinned
  • headroom--top
  • headroom--not-top
  • headroom--bottom
  • headroom--not-bottom

В версиях 0.8–0.11 разработчики часто определяли свои классы вручную через объект classes. В версии 0.12+ стандартные классы были унифицированы, а поддержка кастомных классов изменилась. Старый способ задания всех классов через объект по ключу classes теперь требует точного соответствия новым ключам.

События

onPin / onUnpin / onTop / onNotTop

  • В ранних версиях события передавались в конструктор как функции в объекте callbacks.
  • В версиях 0.12+ был добавлен единый интерфейс событий через методы headroom.on(eventName, callback):
headroom.on("pin", function() {
  console.log("Header закреплен");
});
headroom.on("unpin", function() {
  console.log("Header скрыт");
});
  • Старый способ callbacks: { onPin: ... } теперь считается устаревшим и может не поддерживаться в будущих версиях.

Изменения в API методов

  • destroy: полностью очищает все обработчики событий и возвращает элемент в исходное состояние. В версиях <0.12 метод не удалял автоматически все классы, что могло приводить к визуальным артефактам.
  • init: теперь всегда должен вызываться после изменения опций, иначе новые настройки не применятся.

Миграционные рекомендации при обновлении версии

  1. Проверить объект tolerance и при необходимости заменить число на объект с ключами up и down.
  2. Убедиться, что кастомные CSS-классы соответствуют новым ключам pinned, unpinned, top, notTop, bottom, notBottom.
  3. Переписать колбэки событий на новый формат через headroom.on.
  4. Если используется динамический offset, обновить конфигурацию с учетом функции вместо числа.
  5. После изменения конфигурации всегда вызывать init() заново для корректного применения.

Совместимость с современными фреймворками

  • Headroom.js начиная с версии 0.12 корректно интегрируется с React, Vue и Angular через обёртки и хуки.
  • Старые версии могут конфликтовать с виртуальным DOM, поскольку напрямую манипулируют DOM-элементами.

Эти изменения позволяют Headroom.js быть более гибким, безопасным и предсказуемым, но требуют внимательного анализа при обновлении между версиями, особенно если проект активно использует кастомные классы и обработчики событий.

Оглавление