WS Slider

Подключение

Импортируйте функцию wsSlider из начального файла модуля:

import { wsSlider } from '/core/modules/ws-slider/assets/js/initial.js';

Быстрый старт

Подготовьте корневой элемент, видимую область и дорожку со слайдами:

<div class="slider" data-slider>
    <div class="slider-viewport" data-slider-viewport>
        <div class="slider-track" data-slider-track>
            <div class="slider-slide" data-slider-slide>Первый слайд</div>
            <div class="slider-slide" data-slider-slide>Второй слайд</div>
            <div class="slider-slide" data-slider-slide>Третий слайд</div>
        </div>
    </div>

    <button type="button" data-slider-prev>Назад</button>
    <button type="button" data-slider-next>Вперёд</button>
    <div data-slider-pagination></div>
</div>

Скройте содержимое за пределами видимой области:

.slider-viewport {
    overflow: hidden;
}

Передайте корневой элемент и параметры в wsSlider():

wsSlider(document.querySelector('[data-slider]'), {
    mode: 'carousel',
    autoWidth: false,
    perView: 1,
    gap: 20,
    loop: true,
    swipe: true
});

При autoWidth: false ширина слайдов рассчитывается по значению perView.

HTML-структура

Корневой элемент передаётся первым аргументом в wsSlider() и не требует обязательного data-атрибута.

Обязательные элементы:

• data-slider-viewport — видимая область слайдера
• data-slider-track — дорожка со слайдами
• data-slider-slide — один или несколько слайдов

Необязательные элементы:

• data-slider-prev — кнопка перехода назад
• data-slider-next — кнопка перехода вперёд
• data-slider-pagination — контейнер пагинации

Модуль самостоятельно создаёт кнопки внутри контейнера пагинации.

Стандартные селекторы можно изменить через параметр selectors.

Параметры

Общие параметры

Если передано неизвестное значение mode, используется режим carousel.

Параметры carousel

Если step не задан:

• при autoWidth: true используется шаг 1
• при autoWidth: false используется значение perView

Параметр loop применяется только при наличии нескольких страниц слайдера.

Параметры ticker

Минимальное значение speed после нормализации равно 0.1.

Селекторы

Параметр selectors позволяет использовать собственные классы или data-атрибуты.

Пример:

wsSlider(document.querySelector('.gallery'), {
    selectors: {
        viewport: '.gallery-viewport',
        track: '.gallery-track',
        slide: '.gallery-item',
        prev: '.gallery-prev',
        next: '.gallery-next',
        pagination: '.gallery-pagination'
    }
});

Обязательными остаются элементы, соответствующие селекторам viewport, track и slide.

Адаптивные параметры

Ключи объекта breakpoints обозначают минимальную ширину окна в пикселях.

В режиме carousel можно переопределять:

• perView
• autoWidth
• gap
• step

Пример:

wsSlider(document.querySelector('[data-slider]'), {
    mode: 'carousel',
    autoWidth: false,
    perView: 1,
    gap: 12,
    breakpoints: {
        768: {
            perView: 2,
            gap: 20
        },
        1200: {
            perView: 3,
            gap: 32
        }
    }
});

При ширине окна от 768 пикселей отображаются два слайда, а от 1200 пикселей — три.

В режиме ticker через breakpoints изменяется только gap:

wsSlider(document.querySelector('[data-slider]'), {
    mode: 'ticker',
    gap: 16,
    breakpoints: {
        768: {
            gap: 24
        },
        1200: {
            gap: 32
        }
    }
});

Режим carousel

carousel переключает слайды отдельными шагами.

Используйте его, если нужны:

• кнопки перехода назад и вперёд
• пагинация
• автоматическое переключение
• управление свайпом
• отображение заданного количества слайдов
• слайды разной ширины
• циклическое переключение

Слайды одинаковой ширины

Установите autoWidth: false и укажите количество видимых слайдов:

wsSlider(document.querySelector('[data-slider]'), {
    mode: 'carousel',
    autoWidth: false,
    perView: 3,
    step: 1,
    gap: 24
});

Ширина каждого слайда рассчитывается по ширине видимой области, значению perView и расстоянию gap.

Слайды собственной ширины

При autoWidth: true модуль сохраняет ширину, заданную стилями слайда:

.slider-slide {
    width: 280px;
}

wsSlider(document.querySelector('[data-slider]'), {
    mode: 'carousel',
    autoWidth: true,
    gap: 20
});

Этот режим включён по умолчанию.

Автоматическое переключение

wsSlider(document.querySelector('[data-slider]'), {
    mode: 'carousel',
    autoWidth: false,
    perView: 1,
    autoplay: true,
    autoplayDelay: 4000,
    pauseOnHover: true
});

Autoplay запускается только при наличии нескольких страниц.

Режим ticker

ticker непрерывно перемещает горизонтальную ленту.

Используйте его для:

• логотипов
• карточек партнёров
• коротких сообщений
• непрерывно движущихся списков

Пример:

wsSlider(document.querySelector('[data-slider]'), {
    mode: 'ticker',
    gap: 32,
    speed: 0.5,
    direction: 'left',
    pauseOnHover: true,
    pauseOnInteraction: true
});

В режиме ticker:

• ширина слайдов определяется их содержимым или CSS
• кнопки навигации отключаются
• пагинация не создаётся
• параметры autoplay и autoplayDelay не используются
• для непрерывного движения модуль создаёт служебные копии слайдов

Публичный API

wsSlider(sliderNode, options)

Создаёт и сразу инициализирует слайдер.

Параметры:

Функция возвращает инициализированный экземпляр слайдера.

Пример:

import { wsSlider } from '/core/modules/ws-slider/assets/js/initial.js';

wsSlider(document.querySelector('[data-slider]'), {
    mode: 'carousel'
});

Ошибки и ограничения

Модуль выбрасывает ошибку, если:

• первым аргументом не передан DOM-элемент
• внутри корневого элемента отсутствует viewport
• внутри корневого элемента отсутствует track
• внутри track отсутствуют слайды

Дополнительные ограничения:

• модуль работает только с горизонтальным расположением слайдов
• CSS-стили внешнего вида необходимо добавлять отдельно
• для скрытия содержимого за пределами слайдера установите overflow: hidden у viewport
• автоматического наблюдения за добавлением и удалением слайдов в DOM нет
• адаптивные параметры рассчитываются по ширине окна браузера
• пагинация и кнопки навигации предназначены для режима carousel