Обновление с версии 0.9.x на 0.10.x

Переход с версии 0.9.x на 0.10.x в библиотеке Headroom.js связан с внутренней переработкой архитектуры, улучшением производительности и упрощением API. Несмотря на отсутствие кардинальных изменений в базовой концепции, обновление требует внимательного подхода из-за ряда несовместимостей.

Ключевые направления изменений:

  • переработка механизма инициализации
  • изменение поведения классов состояния
  • оптимизация обработки событий прокрутки
  • отказ от устаревших опций
  • улучшение поддержки модульных сборщиков

Изменения в подключении и инициализации

В версии 0.9.x библиотека чаще всего подключалась через глобальный объект Headroom. В 0.10.x усилился акцент на модульный подход.

До (0.9.x):

var headroom = new Headroom(document.querySelector("header"));
headroom.init();

После (0.10.x):

import Headroom from "headroom.js";

const header = document.querySelector("header");
const headroom = new Headroom(header);
headroom.init();

Важные моменты:

  • Поддержка ES6-модулей стала основной
  • Использование сборщиков (Webpack, Rollup, Vite) стало предпочтительным
  • Глобальная переменная всё ещё возможна, но считается устаревающим подходом

Изменение логики классов состояния

Headroom управляет состояниями элемента через CSS-классы. В версии 0.10.x уточнена логика их применения.

Базовые классы:

Класс Назначение
headroom базовое состояние
headroom--pinned элемент закреплён (виден)
headroom--unpinned элемент скрыт
headroom--top пользователь у верхней границы
headroom--not-top пользователь прокрутил вниз

Изменения:

  • Поведение классов стало более предсказуемым
  • Исключены лишние промежуточные состояния
  • Устранены редкие гонки состояний при резкой прокрутке

Переработка обработки scroll-событий

В 0.9.x использовалась базовая обработка событий scroll, что могло приводить к избыточным вызовам.

В версии 0.10.x:

  • внедрён throttling через requestAnimationFrame
  • уменьшена нагрузка на главный поток
  • улучшена плавность анимации

Принцип работы:

  • события scroll не обрабатываются напрямую
  • обновления состояния происходят в синхронизации с кадрами браузера
  • устраняется “дёргание” при быстрой прокрутке

Изменения в настройках (options)

Некоторые параметры были переосмыслены или уточнены.

offset

Без изменений по синтаксису, но улучшена логика:

offset: 100

Теперь:

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

tolerance

tolerance: {
  up: 5,
  down: 0
}

Изменения:

  • повышена точность определения направления прокрутки
  • устранены ложные срабатывания при микро-движениях

Удалённые и устаревшие возможности

Некоторые элементы API были удалены или признаны устаревшими:

Удалено:

  • неявные зависимости от сторонних библиотек
  • устаревшие полифиллы внутри библиотеки

Рекомендации:

  • использовать современные браузеры или подключать полифиллы отдельно
  • не рассчитывать на внутреннюю поддержку старых API

Улучшения производительности

Версия 0.10.x оптимизирована для:

  • мобильных устройств
  • слабых CPU
  • сложных DOM-структур

Основные изменения:

  • уменьшено количество вычислений на каждом scroll
  • оптимизирован доступ к DOM
  • снижено количество reflow/repaint

Изменения в событиях (callbacks)

Callbacks сохранились, но стали работать стабильнее.

Доступные события:

onPin: function() {},
onUnpin: function() {},
onTop: function() {},
onNotTop: function() {}

Улучшения:

  • гарантирован порядок вызова
  • устранены дублирующиеся вызовы
  • callbacks теперь строго привязаны к состояниям

Работа с CSS и анимациями

В 0.10.x библиотека ещё больше сместилась в сторону разделения логики и представления.

Рекомендованный подход:

.headroom {
  transition: transform 0.3s ease;
}

.headroom--unpinned {
  transform: translateY(-100%);
}

.headroom--pinned {
  transform: translateY(0);
}

Изменения:

  • библиотека не управляет анимациями напрямую
  • только добавляет/удаляет классы
  • вся визуальная логика — на стороне CSS

Поддержка современных инструментов

Версия 0.10.x лучше интегрируется с:

  • Webpack
  • Rollup
  • Vite
  • ES Modules

Преимущества:

  • tree-shaking
  • уменьшение размера бандла
  • удобство использования в SPA (React, Vue, Svelte)

Пошаговая миграция с 0.9.x на 0.10.x

1. Обновление зависимости

npm install headroom.js@^0.10.0

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

  • заменить глобальный доступ на import при необходимости

3. Перепроверка CSS-классов

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

4. Актуализация настроек

  • проверить offset и tolerance
  • убрать устаревшие параметры

5. Тестирование поведения

  • прокрутка вверх/вниз
  • поведение на мобильных устройствах
  • корректность callback-функций

Типичные проблемы при обновлении

1. Хедер “дёргается”

Причина:

  • старые CSS-анимации

Решение:

  • перейти на transform вместо top/margin

2. Callback вызывается слишком часто

Причина:

  • неверные значения tolerance

Решение:

  • увеличить значения up и down

3. Не работает импорт

Причина:

  • отсутствие поддержки ES Modules

Решение:

  • настроить сборщик или использовать UMD-версию

Итоговая структура современного использования

import Headroom from "headroom.js";

const header = document.querySelector("header");

const headroom = new Headroom(header, {
  offset: 80,
  tolerance: {
    up: 5,
    down: 0
  },
  onPin: () => {},
  onUnpin: () => {}
});

headroom.init();
.headroom {
  will-change: transform;
  transition: transform 0.25s ease-in-out;
}

.headroom--unpinned {
  transform: translateY(-100%);
}

.headroom--pinned {
  transform: translateY(0);
}

Ключевые различия версий

Область 0.9.x 0.10.x
Подключение глобальный объект ES Modules
Производительность базовая оптимизирована через rAF
Scroll обработка напрямую через requestAnimationFrame
CSS управление частично встроено полностью на стороне разработчика
API менее строгий более предсказуемый
Совместимость шире (старые браузеры) фокус на современных

Практическое значение обновления

  • уменьшение нагрузки на интерфейс при прокрутке
  • более плавное поведение фиксированных элементов
  • упрощение поддержки кода
  • лучшая интеграция в современные frontend-стеки
Оглавление