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

Подключение через CDN — самый быстрый способ начать работу с библиотекой Headroom.js без установки зависимостей и настройки сборщиков. Скрипт загружается напрямую с удалённого сервера и сразу доступен в браузере.

Подключение библиотеки

Для подключения используется тег <script>, размещённый перед закрывающим тегом </body> или в <head> с атрибутом defer.

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

<script src="https://unpkg.com/headroom.js@0.12.0/dist/headroom.min.js"></script>

Альтернативные CDN:

<script src="https://cdn.jsdelivr.net/npm/headroom.js@0.12.0/dist/headroom.min.js"></script>

Ключевые моменты:

  • версия указывается явно для стабильности (@0.12.0)
  • используется минифицированная версия (.min.js) для оптимальной загрузки
  • доступ к библиотеке осуществляется через глобальный объект Headroom

Подготовка HTML-структуры

Headroom.js управляет видимостью элемента (обычно шапки сайта). Для этого требуется элемент, к которому будет применяться поведение.

Пример:

<header id="header">
  <h1>Сайт</h1>
</header>

Важно:

  • элемент должен иметь уникальный селектор
  • чаще всего используется <header>, но возможны любые блоки

Инициализация Headroom

После загрузки библиотеки необходимо создать экземпляр Headroom и привязать его к элементу.

<script>
  const header = document.querySelector("#header");
  const headroom = new Headroom(header);
  headroom.init();
</script>

Что происходит:

  • создаётся объект Headroom
  • библиотека начинает отслеживать прокрутку страницы
  • к элементу применяются CSS-классы в зависимости от направления скролла

Работа с CSS-классами

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

Основные классы:

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

Пример базовой стилизации:

.headroom {
  transition: transform 0.3s ease;
}

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

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

Поведение:

  • при прокрутке вниз элемент скрывается
  • при прокрутке вверх — появляется

Полный пример

<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="UTF-8">
  <title>Headroom CDN</title>
  <style>
    body {
      margin: 0;
      height: 2000px;
    }

    #header {
      position: fixed;
      top: 0;
      width: 100%;
      background: #333;
      color: white;
      padding: 20px;
    }

    .headroom {
      transition: transform 0.3s ease;
    }

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

    .headroom--unpinned {
      transform: translateY(-100%);
    }
  </style>
</head>
<body>

<header id="header">Навигация</header>

<script src="https://unpkg.com/headroom.js@0.12.0/dist/headroom.min.js"></script>
<script>
  const header = document.querySelector("#header");
  const headroom = new Headroom(header);
  headroom.init();
</script>

</body>
</html>

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

Headroom поддерживает конфигурацию через объект настроек:

const headroom = new Headroom(header, {
  offset: 100,
  tolerance: {
    up: 5,
    down: 0
  },
  classes: {
    initial: "headroom",
    pinned: "headroom--pinned",
    unpinned: "headroom--unpinned"
  }
});

Описание параметров:

  • offset — расстояние прокрутки перед активацией поведения

  • tolerance — чувствительность к скроллу

    • up — при прокрутке вверх
    • down — при прокрутке вниз

  • classes — переопределение CSS-классов

Использование с атрибутом defer

Чтобы избежать блокировки рендеринга страницы:

<script src="https://unpkg.com/headroom.js@0.12.0/dist/headroom.min.js" defer></script>

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

  • скрипт загружается асинхронно
  • выполняется после парсинга HTML
  • безопасно использовать без переноса в конец <body>

Проверка загрузки

При использовании CDN важно учитывать сетевые ошибки. Простейшая проверка:

if (typeof Headroom !== "undefined") {
  const headroom = new Headroom(document.querySelector("#header"));
  headroom.init();
}

Это предотвращает ошибки, если библиотека не загрузилась.

Локальный fallback

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

<script src="https://unpkg.com/headroom.js@0.12.0/dist/headroom.min.js"></script>
<script>
  if (typeof Headroom === "undefined") {
    document.write('<script src="/js/headroom.min.js"><\/script>');
  }
</script>

Таким образом:

  • сначала пробуется CDN
  • при сбое подключается локальная копия

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

Критически важно соблюдать порядок:

  1. HTML-разметка
  2. Подключение Headroom.js
  3. Инициализация

Нарушение порядка приводит к ошибкам:

  • Headroom is not defined
  • Cannot read property of null

Частые ошибки

Элемент не найден

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

Причина:

  • скрипт выполняется до загрузки DOM

Решение:

document.addEventListener("DOMContentLoaded", function () {
  const header = document.querySelector("#header");
  const headroom = new Headroom(header);
  headroom.init();
});

Нет анимации

Причина:

  • отсутствуют CSS-классы

Решение:

  • добавить стили transform и transition

Элемент не фиксирован

Причина:

  • отсутствует position: fixed

Решение:

#header {
  position: fixed;
}

Преимущества CDN-подключения

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

Ограничения

  • зависимость от внешнего сервера
  • невозможность офлайн-работы
  • ограниченный контроль над версией без фиксации

Когда использовать

Подключение через CDN подходит в случаях:

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

При масштабировании проекта обычно переходят на пакетные менеджеры и сборщики, обеспечивающие больший контроль над зависимостями и производительностью.

Оглавление