Swiper

Swiper — движок перелистывания Framework: он сдвигает ряд слайдов по кнопкам, клавишам и вызовам из скрипта. Движок не оформляет слайды и не выбирает поведение за проект. Для готовых переключателей, пагинации и автопрокрутки берите карусель.

Пример

HTML

<section class="flex flex-col gap-2" data-swiper-demo="overview">
  <div class="swiper" role="region" aria-label="Подборка материалов" tabindex="0">
    <div class="swiper-wrapper">
      <div class="swiper-slide p-x-1"><div class="bg-surface-container color-on-surface p-3 radius-3">Слайд 1</div></div>
      <div class="swiper-slide p-x-1"><div class="bg-surface-container color-on-surface p-3 radius-3">Слайд 2</div></div>
      <div class="swiper-slide p-x-1"><div class="bg-surface-container color-on-surface p-3 radius-3">Слайд 3</div></div>
    </div>
  </div>
  <div class="flex gap-1">
    <button type="button" class="sf-icon-button sf-icon-button--icon sf-icon-button--outline sf-icon-button--on-surface sf-icon-button--size-1" aria-label="Предыдущий слайд" data-swiper-prev><i class="sf-icon" aria-hidden="true">chevron_left</i></button>
    <button type="button" class="sf-icon-button sf-icon-button--icon sf-icon-button--outline sf-icon-button--on-surface sf-icon-button--size-1" aria-label="Следующий слайд" data-swiper-next><i class="sf-icon" aria-hidden="true">chevron_right</i></button>
  </div>
</section>

JavaScript

document.querySelectorAll('[data-swiper-demo="overview"]').forEach((demo) => {
  const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
  const start = () => {
    if (typeof window.Swiper !== 'function') return window.setTimeout(start, 50);
    new window.Swiper(demo.querySelector('.swiper'), {
      keyboard: true,
      speed: reducedMotion ? 0 : 300,
      navigation: {
        prevEl: demo.querySelector('[data-swiper-prev]'),
        nextEl: demo.querySelector('[data-swiper-next]'),
      },
    });
  };
  start();
});

Разметка

Минимальную разметку показывает пример выше. Части вложены так: корень swiper → лента swiper-wrapper → слайды swiper-slide.

swiper обрезает ленту по своей ширине; swiper-wrapper выстраивает слайды в строку и сдвигается при перелистывании; каждый swiper-slide по умолчанию занимает всю ширину корня.
Кнопки перелистывания — обычные кнопки Framework в любом месте страницы; движку их передают в параметрах. На первом и последнем слайде кнопка получает класс swiper-button-disabled и приглушается.
Промежуток между слайдами задают отступы внутри слайда (p-x-1), а не поле между ними.
Разметка сама не перелистывается: каждый корень создают явно через new Swiper(root, options).

Варианты

Число видимых слайдов

Параметр slidesPerView задаёт, сколько слайдов видно сразу, а breakpoints меняет его по ширине окна: ключи — минимальная ширина окна в пикселях. Движок читает breakpoints при создании и при вызове update(), поэтому при изменении ширины окна вызывайте update() сами.

HTML

<section class="flex flex-col gap-2" data-swiper-demo="responsive">
  <div class="swiper" role="region" aria-label="Адаптивная подборка" tabindex="0">
    <div class="swiper-wrapper">
      <div class="swiper-slide p-x-1"><div class="bg-surface-container color-on-surface p-3 radius-3">Материал 1</div></div>
      <div class="swiper-slide p-x-1"><div class="bg-surface-container color-on-surface p-3 radius-3">Материал 2</div></div>
      <div class="swiper-slide p-x-1"><div class="bg-surface-container color-on-surface p-3 radius-3">Материал 3</div></div>
      <div class="swiper-slide p-x-1"><div class="bg-surface-container color-on-surface p-3 radius-3">Материал 4</div></div>
      <div class="swiper-slide p-x-1"><div class="bg-surface-container color-on-surface p-3 radius-3">Материал 5</div></div>
      <div class="swiper-slide p-x-1"><div class="bg-surface-container color-on-surface p-3 radius-3">Материал 6</div></div>
    </div>
  </div>
  <div class="flex gap-1">
    <button type="button" class="sf-icon-button sf-icon-button--icon sf-icon-button--outline sf-icon-button--on-surface sf-icon-button--size-1" aria-label="Предыдущий слайд" data-swiper-prev><i class="sf-icon" aria-hidden="true">chevron_left</i></button>
    <button type="button" class="sf-icon-button sf-icon-button--icon sf-icon-button--outline sf-icon-button--on-surface sf-icon-button--size-1" aria-label="Следующий слайд" data-swiper-next><i class="sf-icon" aria-hidden="true">chevron_right</i></button>
  </div>
</section>

JavaScript

document.querySelectorAll('[data-swiper-demo="responsive"]').forEach((demo) => {
  const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
  const start = () => {
    if (typeof window.Swiper !== 'function') return window.setTimeout(start, 50);
    const swiper = new window.Swiper(demo.querySelector('.swiper'), {
      keyboard: true,
      speed: reducedMotion ? 0 : 300,
      slidesPerView: 1,
      breakpoints: {640: {slidesPerView: 2}, 960: {slidesPerView: 3}},
      navigation: {
        prevEl: demo.querySelector('[data-swiper-prev]'),
        nextEl: demo.querySelector('[data-swiper-next]'),
      },
    });
    // The engine reads breakpoints on update(); the page calls it on resize.
    window.addEventListener('resize', () => swiper.update());
  };
  start();
});

Доступность

Корню дайте role="region" и доступное имя через aria-label, а tabindex="0" — если включено управление клавишами.
Движок помечает слайды role="group" и именем «1 / 3», а скрытые слайды — aria-hidden="true". Ссылки и кнопки в скрытых слайдах остаются в порядке фокуса: если они есть, берите карусель — она делает скрытые слайды inert.
Кнопкам перелистывания нужны доступные имена: «Предыдущий слайд», «Следующий слайд».
При параметре keyboard: true стрелки влево и вправо перелистывают слайды, пока фокус внутри корня, с учётом направления письма.
Жестов смахивания движок не обрабатывает: на сенсорном экране нужны видимые кнопки.
При системной настройке уменьшения движения CSS убирает анимацию ленты; передайте и speed: 0.

JavaScript

window.Swiper — конструктор движка. Он появляется, когда скрипт компонента выполнен; карусель Framework ждёт его сама.

Параметры:

Параметр	Что задаёт
`slidesPerView`	число видимых слайдов, по умолчанию 1
`breakpoints`	параметры по минимальной ширине окна
`initialSlide`	номер первого показанного слайда, с нуля
`speed`	длительность сдвига в миллисекундах, по умолчанию 300
`loop`	после последнего слайда перейти к первому
`keyboard`	`true` — перелистывание стрелками
`navigation`	`prevEl`, `nextEl` (элемент или селектор), `disabledClass`
`pagination`	`el`, `clickable`, `bulletElement`, `bulletClass`, `bulletActiveClass` — точки по числу слайдов; своего оформления у точек нет, его задают классы
`autoplay`	`{delay}` — перелистывать сам каждые `delay` миллисекунд

Методы экземпляра: slideNext(), slidePrev(), slideTo(index), update() — после добавления или удаления слайдов и при смене ширины окна, enable() и disable(), autoplay.start() и autoplay.stop(), destroy() — снимает обработчики и стили. Свойства activeIndex и slides дают текущий слайд и список слайдов. События подключает on(name, listener): init, slideChange, transitionEnd, autoplayStart, autoplayStop, destroy; обработчик получает экземпляр.

После изменения набора слайдов вызывайте update() у уже созданного экземпляра — второй экземпляр поверх первого не создавайте.

HTML

<section class="flex flex-col gap-2" data-swiper-demo="lifecycle">
  <div class="flex flex-wrap gap-1">
    <button type="button" class="sf-button sf-button--default sf-button--primary sf-button--size-1/2" data-swiper-add><span class="sf-button-text-container">Добавить слайд</span></button>
    <button type="button" class="sf-button sf-button--outline sf-button--on-surface sf-button--size-1/2" data-swiper-remove><span class="sf-button-text-container">Удалить последний</span></button>
  </div>
  <div class="swiper" role="region" aria-label="Изменяемая подборка" tabindex="0">
    <div class="swiper-wrapper">
      <div class="swiper-slide p-x-1"><div class="bg-surface-container color-on-surface p-3 radius-3">Слайд 1</div></div>
      <div class="swiper-slide p-x-1"><div class="bg-surface-container color-on-surface p-3 radius-3">Слайд 2</div></div>
    </div>
  </div>
  <div class="flex gap-1">
    <button type="button" class="sf-icon-button sf-icon-button--icon sf-icon-button--outline sf-icon-button--on-surface sf-icon-button--size-1" aria-label="Предыдущий слайд" data-swiper-prev><i class="sf-icon" aria-hidden="true">chevron_left</i></button>
    <button type="button" class="sf-icon-button sf-icon-button--icon sf-icon-button--outline sf-icon-button--on-surface sf-icon-button--size-1" aria-label="Следующий слайд" data-swiper-next><i class="sf-icon" aria-hidden="true">chevron_right</i></button>
  </div>
</section>

JavaScript

document.querySelectorAll('[data-swiper-demo="lifecycle"]').forEach((demo) => {
  const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
  const start = () => {
    if (typeof window.Swiper !== 'function') return window.setTimeout(start, 50);
    const root = demo.querySelector('.swiper');
    const wrapper = root.querySelector('.swiper-wrapper');
    const swiper = new window.Swiper(root, {
      keyboard: true,
      speed: reducedMotion ? 0 : 300,
      navigation: {
        prevEl: demo.querySelector('[data-swiper-prev]'),
        nextEl: demo.querySelector('[data-swiper-next]'),
      },
    });

    demo.querySelector('[data-swiper-add]').addEventListener('click', () => {
      const slide = wrapper.firstElementChild.cloneNode(true);
      slide.querySelector('div').textContent = `Слайд ${wrapper.children.length + 1}`;
      wrapper.append(slide);
      swiper.update();
      swiper.slideTo(wrapper.children.length - 1);
    });

    demo.querySelector('[data-swiper-remove]').addEventListener('click', () => {
      if (wrapper.children.length <= 1) return;
      wrapper.lastElementChild.remove();
      swiper.update();
    });
  };
  start();
});

Создание движка с кнопками и числом слайдов по ширине окна:

JavaScript

const swiper = new Swiper(document.querySelector('#gallery'), {
  keyboard: true,
  slidesPerView: 1,
  breakpoints: {640: {slidesPerView: 2}},
  navigation: {prevEl: '#gallery-prev', nextEl: '#gallery-next'},
});
swiper.on('slideChange', (instance) => console.log(instance.activeIndex));

Классы

Что	Классы
Блок	`swiper`
Части	`swiper-button-disabled`, `swiper-slide`, `swiper-wrapper`

Классы и переменные собраны из CSS выпуска и обновляются вместе с ним.

Навигация

Главное

Документация

Содержание

Swiper

Пример

Разметка

Варианты

Число видимых слайдов

Доступность

JavaScript

Классы

См. также

Настройки

Swiper

Пример

Разметка

Варианты

Число видимых слайдов

Доступность

JavaScript

Классы

См. также

Поиск по документации