Интеграция с системами сборки

Для интеграции Headroom.js в современный проект рекомендуется использовать менеджеры пакетов. Установка через npm выполняется командой:

npm install headroom.js

или через yarn:

yarn add headroom.js

После установки модуль можно импортировать в проект:

import Headroom from 'headroom.js';

Для старых систем сборки, поддерживающих CommonJS, возможен вариант:

const Headroom = require('headroom.js');

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

Если проект не использует сборщик модулей, библиотеку можно подключить напрямую через CDN:

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

После подключения объект Headroom становится доступен глобально:

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

Конфигурация в сборщиках (Webpack, Vite, Parcel)

Webpack: Необходимо убедиться, что библиотека корректно обрабатывается через babel-loader или другой транспайлер, если используются современные синтаксические возможности ES6+. Типовая конфигурация для импорта Headroom.js:

// main.js
import Headroom from 'headroom.js';

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

Vite: Vite поддерживает ES-модули из коробки, поэтому достаточно простого импорта через import Headroom from 'headroom.js';. Важно убедиться, что при использовании SSR (Server Side Rendering) доступ к document проверяется:

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

Parcel: Parcel автоматически обрабатывает npm-пакеты, поэтому импорт и инициализация аналогичны примеру для Webpack.

Настройка через конфигурационные файлы

Для проектов с разделением логики и конфигурации рекомендуется вынести параметры Headroom в отдельный модуль:

// headroom-config.js
export const headroomOptions = {
  tolerance: 5,
  offset: 50,
  classes: {
    initial: "headroom",
    pinned: "headroom--pinned",
    unpinned: "headroom--unpinned"
  },
  onPin: () => console.log("Header pinned"),
  onUnpin: () => console.log("Header unpinned")
};

Импорт конфигурации в основной файл:

import Headroom from 'headroom.js';
import { headroomOptions } from './headroom-config';

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

Интеграция с CSS-предпроцессорами

Headroom.js работает в паре с CSS-классами для управления состояниями шапки. При использовании Sass или Less рекомендуется определить базовые и модифицирующие классы:

.headroom {
  transition: transform 0.2s ease-in-out;
}

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

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

При сборке с помощью Webpack или Vite SCSS-файлы можно импортировать напрямую в JS:

import './styles/header.scss';

Использование с фреймворками

React: Для React удобно обернуть Headroom.js в хук useEffect:

import React, { useEffect } from 'react';
import Headroom from 'headroom.js';

function Header() {
  useEffect(() => {
    const header = document.querySelector("header");
    const headroom = new Headroom(header);
    headroom.init();
    return () => headroom.destroy();
  }, []);

  return <header className="headroom">Навигация</header>;
}

Vue: В Vue Headroom можно инициализировать в mounted:

import Headroom from 'headroom.js';

export default {
  mounted() {
    const header = this.$refs.header;
    this.headroom = new Headroom(header);
    this.headroom.init();
  },
  beforeUnmount() {
    this.headroom.destroy();
  }
};

<template>
  <header ref="header" class="headroom">Меню</header>
</template>

Angular: Для Angular создается сервис или директива, которая управляет экземпляром Headroom:

import { Directive, ElementRef, AfterViewInit, OnDestroy } from '@angular/core';
import Headroom from 'headroom.js';

@Directive({
  selector: '[appHeadroom]'
})
export class HeadroomDirective implements AfterViewInit, OnDestroy {
  private headroom!: Headroom;

  constructor(private el: ElementRef) {}

  ngAfterViewInit() {
    this.headroom = new Headroom(this.el.nativeElement);
    this.headroom.init();
  }

  ngOnDestroy() {
    this.headroom.destroy();
  }
}

Оптимизация для сборки

Минификация: использовать terser или встроенные плагины сборщиков, чтобы сократить размер Headroom.js.
Tree Shaking: при импорте только нужных модулей сборщики удаляют неиспользуемый код.
Кэширование: подключение через npm позволяет использовать кэшированные зависимости для ускорения сборки.
Асинхронная загрузка: можно динамически импортировать Headroom для ленивой загрузки:

import('headroom.js').then(({ default: Headroom }) => {
  const header = document.querySelector("header");
  const headroom = new Headroom(header);
  headroom.init();
});

Взаимодействие с другими библиотеками

При использовании с анимационными библиотеками (GSAP, Anime.js) важно синхронизировать классы .headroom--pinned и .headroom--unpinned с анимациями.
В SPA необходимо пересоздавать экземпляр Headroom при смене маршрутов, чтобы корректно обновлялись ссылки на DOM-элементы.
Для проектов с серверным рендерингом следует проверять наличие window и document перед инициализацией.