OnlyScrollbar

Кастомный скроллбар, который позволяет дополнить стандартное поведение браузера и добавляет инерцию для увеличения плавности

Установка

С помощью npm:

npm install only-scrollbar

Использование

Рекомендуется использование синтаксиса ES6, с применением import

import OnlyScrollbar from 'only-scrollbar';

const scroll = new OnlyScrollbar(document.querySelector('.scroll-container'));

Контейнер, в котором будет проинициализирован скрол должен придерживаться тех же правил, что и обычный скрол-контейнер:

• Контейнер должен быть ограничен по высоте
• Значение css-правила overflow в данном случае необязательно, так как правило overflow: auto добавляется автоматически

Конструктор класса OnlyScrollbar принимает до двух аргументов:

Возможные параметры инициализации (OnlyScrollbarOptions)

Возможные параметры для настройки ссылок-якорей

В случае использования type: 'custom' необходимо использовать атрибуты data-os-anchor и data-os-anchor-id. Элементы с одинаковыми значениями таких атрибутов будут обрабатываться аналогично стандартному браузерному поведению с атрибутами href и id

import OnlyScrollbar from 'only-scrollbar';

const scroll = new OnlyScrollbar('#scroll-container-id', {
    damping: 0.8,
    eventContainer: window,
    anchors: {
        type: 'custom',
        offset: 200
    }
});

API

Для обращения к свойствам и методам класса OnlyScrollbar, требуется создать экземпляр класса

import OnlyScrollbar from 'only-scrollbar';

const scroll = new OnlyScrollbar('.scroll-container');
scroll.destroy();

• Свойства

  • OnlyScrollbar.Attributes
  • OnlyScrollbar.ClassNames
  • OnlyScrollbar.Events
  • OnlyScrollbar.scrollContainer
  • OnlyScrollbar.eventContainer
  • OnlyScrollbar.options
  • OnlyScrollbar.isLocked
  • OnlyScrollbar.position
  • OnlyScrollbar.direction
  • OnlyScrollbar.isStart
  • OnlyScrollbar.isEnd
  • OnlyScrollbar.isScrolling

• Методы

  • OnlyScrollbar.scrollTo
  • OnlyScrollbar.scrollIntoView
  • OnlyScrollbar.setValue
  • OnlyScrollbar.stop
  • OnlyScrollbar.lock
  • OnlyScrollbar.unlock
  • OnlyScrollbar.addEventListener
  • OnlyScrollbar.removeEventListener
  • OnlyScrollbar.destroy

• События

  • os:start
  • os:stop
  • os:change
  • os:reachEnd
  • os:reachStart
  • os:lock
  • os:unlock

Свойства

OnlyScrollbar.Attributes

Статичное поле класса. Содержит названия, используемых data-атрибутов

OnlyScrollbar.СlassNames

Статичное поле класса. Содержит перечень основных css-классов, которые добавляются на scrollContainer

OnlyScrollbar.Events

Статичное поле класса. Содержит названия, кастомных js-событий

OnlyScrollbar.scrollContainer

• Type: HTMLElement

Основной контейнер внутри которого происходит скрол и все основные расчеты

Для того чтобы применить плавный скрол для всей страницы, в качестве контейнера достаточно указать объект window или document.scrollingElement

Объект window не может быть контейнером для скрола, но вместо него будет установлен document.scrollingElement

OnlyScrollbar.eventContainer

• Type: HTMLElement | Window

Элемент, на который будут применяться все события

В отличие от scrollContainer может быть объектом window, но не document.scrollingElement

OnlyScrollbar.options

Хранит параметры инициализации

OnlyScrollbar.isLocked

• Type: boolean

Логическое значение, показывающее заблокирован ли скрол.

Заблокированный скрол не позволяет выполняться событиям синхронизации и событиям для перерасчета позиции. Не блокирует скрол на touch-устройствах

OnlyScrollbar.position

• Type: number

Текущее значение позиции скрола. Значение поля scrollTop или scrollLeft в зависимости от направления скрола

OnlyScrollbar.direction

• Type: Direction

type Direction = 1 | -1

Возвращает текущее направление скрола в числовом представлении: 1 = Down/Right, -1 = Up/Left

OnlyScrollbar.isStart

• Type: boolean

Возвращает true, если текущая позиция = 0

OnlyScrollbar.isEnd

• Type: boolean

Возвращает true, если текущая позиция совпадает с максимально возможной позицией внутри скрол-контейнера

OnlyScrollbar.isScrolling

• Type: boolean

Возвращает true, если в данный момент выполняется плавный скрол

Методы

OnlyScrollbar.scrollTo

scroll.scrollTo(position: number): void

Плавный скрол до конкретной позиции, с применением стандартных расчетов для вычисления промежуточных значений

Example:

scroll.scrollTo(600);

OnlyScrollbar.scrollIntoView

scroll.scrollIntoView(element: HTMLElement, offset?: number): void

Плавный скрол до переданного элемента с применением дополнительного отступа, если такой необходим

Example:

const targetElement = document.querySelector('#target');
scroll.scrollIntoView(targetElement, 200);

OnlyScrollbar.setValue

scroll.setValue(value: number): void

Установка конкретного значения позиции скрола, без применения каких-либо анимаций

Example:

scroll.setValue(600);

OnlyScrollbar.stop

scroll.stop(): void

Останавливает скрол на текущей позиции

OnlyScrollbar.lock

scroll.lock(): void

Блокирует скрол

Блокировка также вызовет метод stop

OnlyScrollbar.unlock

scroll.unlock(): void

Разблокирует скрол.

OnlyScrollbar.addEventListener

scroll.addEventListener(type: OnlyScrollbarEvents, eventHandler: EventHandler, options: AddEventListenerOptions): void

Добавляет обработчик события на eventContainer

const scrollEndHandler = () => {
    /* ... */
}
scroll.addEventListener('scrollEnd', scrollEndHandler, { once: true });

OnlyScrollbar.removeEventListener

scroll.removeEventListener(type: OnlyScrollbarEvents, eventHandler: EventHandler): void

Удаляет существующий обработчик события на eventContainer

const scrollEndHandler = () => {
    /* ... */
}
scroll.removeEventListener('scrollEnd', scrollEndHandler);

OnlyScrollbar.destroy

scroll.destroy(): void

Очистка событий, таймеров, классов и атрибутов

События

os:start

Начало процесса плавного скрола

os:end

Завершение процесса плавного скрола

os:change

Изменение направления скрола

os:reachEnd

Достижение нижней/правой границы скрол-контейнера

os:reachStart

Достижение верхней/левой границы скрол-контейнера

os:lock

Блокировка скрола

os:unlock

Разблокировка скрола