Сигнатуры функций

Stickybits — это легковесная библиотека JavaScript, предназначенная для управления «липкими» элементами на веб-странице. Основная цель библиотеки — упрощение процесса фиксации элементов при прокрутке страницы без необходимости вручную писать сложные CSS-трюки или отслеживание событий скролла.

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

Конструктор Stickybits

stickybits(target, options)

Аргументы:

  • target — элемент или селектор CSS, к которому применяется поведение sticky. Может быть строкой (например, '.header') или DOM-элементом.

  • options — объект конфигурации, который может содержать следующие свойства:

    • useStickyClasses (boolean, по умолчанию true) — добавляет CSS-классы .js-is-sticky, .js-is-stuck для отслеживания состояния элемента.
    • stickyBitStickyOffset (number, по умолчанию 0) — смещение от верхней границы при фиксации.
    • parentClass (string, по умолчанию 'js-stickybit-parent') — класс родительского контейнера.
    • customStickyChangeNumber (number, по умолчанию 0) — точка скролла, после которой элемент становится sticky.
    • verticalPosition (string, по умолчанию 'top') — позиция фиксации: 'top' или 'bottom'.
    • noStyles (boolean, по умолчанию false) — отключает встроенные стили библиотеки.

Возвращаемое значение:

  • Объект Stickybits, который содержит методы управления поведением элемента.

Методы объекта Stickybits

update()

stickybitsInstance.update()
  • Пересчитывает позиции элементов и обновляет их состояния.
  • Используется при динамическом изменении контента страницы или размеров элементов.

cleanup()

stickybitsInstance.cleanup()

  • Убирает все изменения, внесённые библиотекой:

    • удаляет классы .js-is-sticky, .js-is-stuck;
    • возвращает элементы в исходное состояние.

addInstance(target)

stickybitsInstance.addInstance(target)
  • Позволяет добавить новый элемент для отслеживания после инициализации Stickybits.
  • target — DOM-элемент или селектор.

removeInstance(target)

stickybitsInstance.removeInstance(target)
  • Убирает конкретный элемент из контроля Stickybits.
  • Применяется, когда элемент больше не должен быть sticky.

Важные сигнатуры обратного вызова

Stickybits поддерживает кастомные классы состояния, что позволяет следить за событиями скролла через CSS. При включённой опции useStickyClasses библиотека автоматически меняет классы:

  • .js-is-sticky — элемент в состоянии «липкий».
  • .js-is-stuck — элемент достиг нижней границы родителя.
  • .js-is-unstuck — элемент вернулся в исходное положение.

Сигнатуры этих классов можно использовать в собственных JavaScript-функциях:

document.querySelector('.header').addEventListener('stickybit:statechange', (event) => {
  console.log(event.detail);
});

  • event.detail возвращает объект состояния элемента:

    • isSticky — boolean, true если элемент липкий;
    • isStuck — boolean, true если элемент достиг нижней границы;
    • parent — DOM-элемент родителя;
    • el — DOM-элемент sticky.

Конфигурация позиционирования

Stickybits позволяет изменять позицию фиксации через параметр verticalPosition:

stickybits('.sidebar', { verticalPosition: 'bottom' });
  • 'top' — стандартное поведение: элемент фиксируется к верхней границе окна.
  • 'bottom' — элемент фиксируется к нижней границе, что полезно для футеров и нижних панелей.

Примеры вызова и работы функций

// Инициализация
const sticky = stickybits('.header', {
  useStickyClasses: true,
  stickyBitStickyOffset: 10,
  verticalPosition: 'top'
});

// Добавление нового элемента после инициализации
sticky.addInstance('.sidebar');

// Пересчёт после изменения DOM
sticky.update();

// Удаление всех изменений
sticky.cleanup();
  • Методы вызываются цепочкой через объект Stickybits, что упрощает управление несколькими элементами на странице.
  • Stickybits гарантирует корректное взаимодействие с DOM и минимальное вмешательство в CSS.

Советы по использованию

  • Для элементов с динамическим контентом рекомендуется периодически вызывать update().
  • Если требуется полностью удалить функциональность, cleanup() восстанавливает исходное состояние элементов.
  • Классы .js-is-sticky и .js-is-stuck позволяют интегрировать анимации и CSS-переходы без изменения логики JavaScript.

Stickybits реализует лёгкую абстракцию над нативной CSS-свойством position: sticky, добавляя возможности контроля через JavaScript. Понимание сигнатур всех функций библиотеки позволяет строить сложные интерфейсы с динамическими sticky-элементами, не нарушая производительность страницы.

Оглавление