Smart-слайдер

<sf-slider> — последовательность слайдов, которую листают стрелками, точками, миниатюрами или жестом. Он собирает разметку слайдера вокруг переданных слайдов и подключает его поведение. Берите его для материалов, которые смотрят по одному; то, что нужно сравнить, выкладывайте на странице рядом.

Пример

<sf-slider root-class="sf-slider--content">
  <article slot="slide" class="radius-default bg-primary-container p-2"><h3>Выпуск документации</h3><p>Справочник компонентов собран из манифестов выпуска.</p></article>
  <article slot="slide" class="radius-default bg-secondary-container p-2"><h3>Новая тема</h3><p>Тёмная тема доступна во всех разделах сайта.</p></article>
  <article slot="slide" class="radius-default bg-tertiary-container p-2"><h3>Встреча команды</h3><p>Обсуждаем план работ на следующий квартал.</p></article>
</sf-slider>

Применение

Слайды

Каждый непосредственный дочерний элемент с slot="slide" становится одним слайдом. Заголовок, текст и действие одной карточки держите внутри одного такого элемента. Пробелы и комментарии между элементами слайдами не становятся. slide-class добавляет утилиты обёртке каждого слайда.

Текст или изображения

root-class="sf-slider--content" ставит стрелки и точки в поток под слайдами — для текста и карточек, как в примере. Без этого класса навигация лежит поверх слайдов, что подходит изображениям.

Навигация

arrows и dots включают стрелки и точки; оба включены по умолчанию. button-type выбирает вид стрелок — primary, secondary, dark или light, button-size — их размер. dots-type и dots-size задают вид и размер точек. loop замыкает последовательность.

thumbs добавляет под слайдами полосу миниатюр: если в слайде есть изображение или видео, миниатюра показывает его, иначе — копию слайда. thumbs-class и thumb-class добавляют утилиты полосе и каждой миниатюре.

<sf-slider thumbs="true" dots="false" arrows="true">
  <div slot="slide" class="radius-default bg-primary color-on-primary p-3">Первый слайд</div>
  <div slot="slide" class="radius-default bg-secondary color-on-secondary p-3">Второй слайд</div>
  <div slot="slide" class="radius-default bg-tertiary color-on-tertiary p-3">Третий слайд</div>
</sf-slider>

Движение и автопрокрутка

Без space-between и speed расстояние между слайдами и длительность перехода берутся из токенов Framework; числа в этих атрибутах их переопределяют. data-autoplay="true" на элементе включает автопрокрутку, data-autoplay-delay задаёт паузу в миллисекундах. Автопрокрутка останавливается, пока фокус внутри слайдера и пока вкладка скрыта. При системной настройке «уменьшить движение» переход мгновенный, а автопрокрутка не запускается.

Оформление

root-class, slide-class, thumbs-class и thumb-class принимают утилиты Framework: цветовые роли, отступы и радиусы задавайте ими, без своих стилей. Изменение только оформления сохраняет текущий слайд и фокус.

<sf-slider root-class="sf-slider--content bg-surface-container radius-default p-2" button-type="secondary" dots-type="primary-light" dots-size="1" loop="true">
  <div slot="slide" class="bg-surface-container radius-default p-2">Оформление через утилиты Framework</div>
  <div slot="slide" class="bg-surface-container radius-default p-2">Размеры и движение наследуют токены</div>
</sf-slider>

Управление из кода

slideNext() и slidePrev() листают вперёд и назад. Смена слайда отправляет всплывающее событие sf-slide-change; в event.detail activeIndex — номер текущего слайда, previousIndex — прошлого, realIndex — номер слайда без учёта копий, которые добавляет loop. refresh() пересчитывает раскладку после изменения размеров контейнера, getSlider() возвращает экземпляр Swiper для настроек, которых нет в атрибутах.

const slider = document.querySelector('sf-slider');
slider.addEventListener('sf-slide-change', (event) => {
  counter.textContent = `${event.detail.realIndex + 1} из 3`;
});
slider.slideNext();

Доступность

• Дайте слайдеру имя: поместите его в <section> с заголовком или aria-labelledby, чтобы экранный диктор назвал область.
• Стрелки — кнопки в порядке Tab. Их доступные имена английские — «Previous slide» и «Next slide» — и атрибутом не меняются.
• Слайды вне видимой области недоступны для фокуса и вспомогательных технологий: ссылки и кнопки в них не попадают в порядок Tab.
• Не прячьте в автопрокрутку единственную копию важных сведений.

Справочник API

Раздел собран из манифеста компонента выпуска ui-106d5901f8c3 и обновляется вместе с выпуском. Чтобы исправить описание, исправьте манифест.

Каждому атрибуту соответствует свойство элемента с тем же именем в camelCase: search-placeholder — searchPlaceholder. Свойство атрибута template называется templateName.

Атрибуты

• button-type — string, по умолчанию primary.
• button-size — string, по умолчанию 1.
• dots — boolean, по умолчанию true.
• dots-type — string, по умолчанию primary-dark.
• dots-size — string, по умолчанию 2.
• thumbs — boolean, по умолчанию false.
• thumbs-class — string, по умолчанию пусто.
• thumb-class — string, по умолчанию пусто.
• arrows — boolean, по умолчанию true.
• loop — boolean, по умолчанию false.
• space-between — number, по умолчанию 12.
• speed — number, по умолчанию 450.
• root-class — string, по умолчанию пусто.
• slide-class — string, по умолчанию пусто.

Методы

• getSlider() — возвращает object | null. Экземпляр Swiper, на котором построен слайдер, или null до привязки.
• refresh() — возвращает object. Заново привязывает слайдер после изменения его слайдов: передаёт data-атрибуты и пересоздаёт Swiper, сохраняя привязанные события. Возвращает элемент.
• slideNext() — возвращает object. Переходит к следующему слайду, как стрелка «вперёд». Возвращает элемент.
• slidePrev() — возвращает object. Переходит к предыдущему слайду, как стрелка «назад». Возвращает элемент.

События

Все события приходят на сам элемент и всплывают. Общие события базового элемента перечислены в главе Жизненный цикл → Этапы.

• sf-slide-change — detail: { component: object, tagName: string, template: string, activeIndex: number, realIndex: number, previousIndex: number }.

Доступность

• Доступное имя: рекомендуется.
• Клавиши: Tab.
• Фокус: Сохраняет видимый фокус на активном элементе управления.

Минимальная разметка

<sf-slider></sf-slider>

Источник

• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/smart/slider
• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/rule/rule.json#name=cl-slider