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-селектор, по которому будет найден первый подходящий элемент. Является основным контейнером внутри котрого происходит скрол и все расчеты | | element | OnlyScrollbarOptions \| undefined | Параметры инициализации |

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

| parameter | type | default | description | | :-------: | :--: | :-----: | :---------- | | damping | number | 1 | Сила замедления инерции. Рекомендуется указывать значения в промежутке от 0 до 1 | | eventContainer | HTMLHtmlElement \| Element \| Window \| string | scrollContainer | HTML-элемент или css-селектор, по которому будет найден первый подходящий элемент. Является элементом, который будет обрабатывать события, предназначавшиеся скрол контейнеру. По умолчанию равен основному скрол контейнеру | | mode | "vertical" | "horizontal" | "free" | "vertical" | Допустимое направление скрола

import OnlyScrollbar from 'only-scrollbar';

const scroll = new OnlyScrollbar('#scroll-container-id', {
    damping: 0.8,
    eventContainer: window,
    mode: 'free'
});

API

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

import OnlyScrollbar from 'only-scrollbar';

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

• Свойства

  • OnlyScrollbar.classNames
  • OnlyScrollbar.scrollContainer
  • OnlyScrollbar.eventContainer
  • OnlyScrollbar.isLocked
  • OnlyScrollbar.direction
  • OnlyScrollbar.position

• Методы

  • OnlyScrollbar.sync
  • OnlyScrollbar.scrollTo
  • OnlyScrollbar.setValue
  • OnlyScrollbar.lock
  • OnlyScrollbar.unlock
  • OnlyScrollbar.addEventListener
  • OnlyScrollbar.removeEventListener
  • OnlyScrollbar.destroy

• События

  • scrollEnd
  • changeDirectionY
  • changeDirectionX

Свойства

OnlyScrollbar.classNames

• Type: ClassNames

Перечень основных css-классов, которые добавляются на scrollContainer

type ClassName = {
    container: string;
    lock: string;
}

OnlyScrollbar.scrollContainer

• Type: HTMLElement

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

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

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

OnlyScrollbar.eventContainer

• Type: HTMLElement | Window

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

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

OnlyScrollbar.isLocked

• Type: boolean

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

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

OnlyScrollbar.direction

• Type: Direction

type Direction = {
    x: 1 | -1;
    y: 1 | -1;
}

Последнее направление скрола.

Возвращает объект с полями y и x, где 1 = Down/Right, -1 = Up/Left

OnlyScrollbar.position

• Type: Delta2D

type Delta2D = {
    x: number;
    y: number;
}

Текущее значение позиции скрола

Методы

OnlyScrollbar.sync

scroll.sync(): void

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

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

OnlyScrollbar.scrollTo

scroll.scrollTo(position: Delta2D): void

| argument | type | description | | :------: | :--: | :---------- | | position | Delta2D | Объект с целевыми координатами x и y |

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

Example:

scroll.scrollTo({x: 0, y: document.querySelector('#anchor').offsetTop});

OnlyScrollbar.setValue

scroll.setValue(value: number): void

| argument | type | description | | :------: | :--: | :---------- | | position | Delta2D | Объект с целевыми координатами x и y |

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

Example:

scroll.setValue({x: 0, y: document.querySelector('#anchor').offsetTop});

OnlyScrollbar.lock

scroll.lock(): void

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

Блокировка также прервет запущенные процессы по перерасчету позиции

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

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

События

scrollEnd

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

changeDirectionY

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

changeDirectionX

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