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 принимает до двух аргументов:

| argument | type | description | |:--------:|:---------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------| | element | HTMLHtmlElement \| Element \| Window \| string \| null \| undefined | HTML-элемент или css-селектор, по которому будет найден первый подходящий элемент. Является основным контейнером внутри которого происходит скрол и все расчеты | | options | OnlyScrollbarOptions \| undefined | Параметры инициализации |

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

| parameter | type | description | |:--------------:|:------------------------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | damping | number | Сила замедления инерции. Рекомендуется указывать значения в промежутке от 0 до 1. Значение по умолчанию 1 | | eventContainer | HTMLHtmlElement \| Element \| Window \| string | HTML-элемент или css-селектор, по которому будет найден первый подходящий элемент. Является элементом, который будет обрабатывать события, предназначавшиеся скрол контейнеру. По умолчанию равен основному скрол контейнеру | | speed | number | Модификатор скорости для колесика мыши. Значение по умолчанию 1 | | anchors | AnchorsOptions | Дополнительные опции для ссылок-якорей. По умолчанию включена обработка нативных браузерных якорей через хэш в ссылках | | axis | Y | X | Направление скрола. По умолчанию Y | | listenAxis | Y | X | Ось, которая будет прослушиваться обработчиком событий. По умолчанию совпадает со значением параметра axis |

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

| parameter | type | description | |:---------------:|:--------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | offset | number | Отступ от верхней границы экрана в пикселях. По умолчанию 0 | | stopPropagation | boolean | Предотвращает всплытие события click. По умолчанию false | | active | boolean | Определяет наличие обработки ссылок-якорей. По умолчанию true | | root | HTMLElement | Определяет элемент, внутри которого будет обрабатываться событие click по якорям. Полезно, если якоря находятся за пределами scrollContainer. По умолчанию является scrollContainer | | type | native | custom | Позволяет выбрать тип обработки якорей. По умолчанию native |

В случае использования 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

| argument | type | description | |:----------:|:--------:|:-----------------------| | position | number | Целевая позиция скрола |

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

Example:

scroll.scrollTo(600);

OnlyScrollbar.scrollIntoView

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

| argument | type | description | |:---------:|:-------------:|:-----------------------------------| | element | HTMLElement | Целевой HTML-элемент | | offset | number | Смещение скрола (По умолчанию = 0) |

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

Example:

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

OnlyScrollbar.setValue

scroll.setValue(value: number): void

| argument | type | description | |:--------:|:--------:|:-----------------------| | value | number | Целевая позиция скрола |

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

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

| argument | type | description | |:--------------:|:-------------------------:|:----------------------------------------------------------------------------------------------| | type | OnlyScrollbarEvents | Название события. Возможно использовать стандарные события браузера или события OnlyScrollbar | | eventHandler | EventHandler | Функция обработчик события | | options | AddEventListenerOptions | Параметры обработчика события |

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

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

OnlyScrollbar.removeEventListener

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

| argument | type | description | |:--------------:|:---------------------:|:----------------------------------------------------------------------------------------------| | type | OnlyScrollbarEvents | Название события. Возможно использовать стандарные события браузера или события OnlyScrollbar | | eventHandler | EventHandler | Функция обработчик события |

Удаляет существующий обработчик события на 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

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