Перейти к основному содержанию Перейти к навигации по документам
Check
Cмотреть на GitHub

Карусель

Компонент слайд-шоу для цикличного повторения элементов - карусель изображений или текстовых слайдов.

Как это работает

«Карусель» - это слайд-шоу для отображения серии содержимого, созданная на основе CSS 3D-трансформаций и немного на JavaScript. Она работает с текстом, изображениями или обычной разметкой. Она также поддерживает кнопки “next/prev”.

В браузерах с поддержкой API видимости страниц элементы карусели не будут сменяться, когда страница невидима пользователю (например, когда вкладка браузера неактивна, или окно браузера «минимизировано» - кнопка «квадратик» слева от крестика «закрыть браузер», и т.д.).

Эффект анимации этого компонента зависит от медиа запроса prefers-reduced-motion. Смотрите раздел о редукции анимаций.

Учтите, что вложенные карусели не поддерживаются, а карусели в целом не очень желательны «стандартам доступности».

Пример

Карусель не подстраивает автоматически размер содержимого слайдов. Поэтому вам могут понадобиться дополнительные утилиты для придания их содержимому нужного размера. Пока карусели поддерживают кнопки «prev/next», их не надо добавлять явно. Добавьте и настраивайте их самостоятельно.

Класс .active добавляют к одному из слайдов, иначе карусель не будет видно. Также для внедрения элементов управления необходимо задать уникальный ID элементу класса .carousel, особенно если у вас много каруселей на одной странице. Элементы управления и индикаторы должны иметь атрибут data-target (или href для <a>), который совпадает с ID элемента класса .carousel.

Задавайте уникальный id классу .carousel для возможности гибкого управления, особенно если вы используете много каруселей на странице.

Только слайды

Вот пример карусели, где есть только слайды. Заметьте присутствие классов .d-block и .w-100, отменяющих дефолтное выравнивание изображений в браузерах у изображений карусели.

html
<div id="carouselExampleSlidesOnly" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
</div>

С элементами управления

Добавляет кнопки prev/next:

html
<div id="carouselExampleControls" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControls"  data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Предыдущий</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleControls"  data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Следующий</span>
  </button>
</div>

С индикаторами

Вы также можете добавить индикаторы в карусель вместе с элементами управления.

html
<div id="carouselExampleIndicators" class="carousel slide" data-bs-ride="true">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Предыдущий</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Следующий</span>
  </button>
</div>

С надписями

Легко добавляйте подписи к слайдам с помощью элемента .carousel-caption внутри любого .carousel-item. Их можно легко скрыть в меньших окнах просмотра, как показано ниже, с помощью дополнительных утилит отображения. Сначала мы скрываем их с помощью .d-none и возвращаем их на устройства среднего размера с помощью .d-md-block.

html
<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="false">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Метка первого слайда</h5>
        <p>Некоторый репрезентативный заполнитель для первого слайда.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Метка второго слайда</h5>
        <p>Некоторый репрезентативный заполнитель для второго слайда.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Метка третьего слайда</h5>
        <p>Некоторый репрезентативный заполнитель для третьего слайда.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Предыдущий</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Следующий</span>
  </button>
</div>

Плавный переход

Добавьте .carousel-fade в вашу карусель для анимации слайдов с постепенным переходом на следующий слайд.

html
<div id="carouselExampleFade" class="carousel slide carousel-fade" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleFade"  data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Предыдущий</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleFade"  data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Следующий</span>
  </button>
</div>

Добавьте data-interval="" к элементу .carousel-item, чтобы изменить время задержки между автоматическим циклическим переходом к следующему элементу.

html
<div id="carouselExampleInterval" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleInterval"  data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Предыдущий</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleInterval"  data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Следующий</span>
  </button>
</div>

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

Карусели поддерживают смахивание влево/вправо на устройствах с сенсорным экраном для перемещения между слайдами. Это можно отключить с помощью атрибута data-bs-touch. Пример ниже также не включает атрибут data-bs-ride и имеет data-bs-interval="false", поэтому он не запускается автоматически.

html
<div id="carouselExampleControlsNoTouching" class="carousel slide" data-bs-touch="false" data-bs-interval="false">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Предыдущий</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Следующий</span>
  </button>
</div>

Темный вариант

Добавьте .carousel-dark к .carousel для отображения более темных элементов управления, индикаторов и подписей. По умолчанию элементы управления инвертированы и смотрятся более темными по сравнению с их белой заливкой благодаря свойству CSS filter. Заголовки и элементы управления имеют дополнительные Sass переменные, которые настраивают цвет color и цвет фона background-color.

html
<div id="carouselExampleDark" class="carousel carousel-dark slide" data-bs-ride="carousel">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Метка первого слайда</h5>
        <p>Некоторый репрезентативный заполнитель для первого слайда.</p>
      </div>
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Метка второго слайда</h5>
        <p>Некоторый репрезентативный заполнитель для второго слайда.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Метка третьего слайда</h5>
        <p>Некоторый репрезентативный заполнитель для третьего слайда.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleDark"  data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Предыдущий</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleDark"  data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Следующий</span>
  </button>
</div>

Изменение продолжительности перехода

Длительность перехода .carousel-item может быть изменена с помощью переменной Sass $carousel-transition-duration перед компиляцией или настраиваемыми стилями, если вы используете скомпилированный CSS. Если применяется несколько переходов, убедитесь, что сначала определен переход преобразования (например, transition: transform 2s ease, opacity .5s ease-out).

Sass

Переменные

$carousel-control-color:             $white;
$carousel-control-width:             15%;
$carousel-control-opacity:           .5;
$carousel-control-hover-opacity:     .9;
$carousel-control-transition:        opacity .15s ease;

$carousel-indicator-width:           30px;
$carousel-indicator-height:          3px;
$carousel-indicator-hit-area-height: 10px;
$carousel-indicator-spacer:          3px;
$carousel-indicator-opacity:         .5;
$carousel-indicator-active-bg:       $white;
$carousel-indicator-active-opacity:  1;
$carousel-indicator-transition:      opacity .6s ease;

$carousel-caption-width:             70%;
$carousel-caption-color:             $white;
$carousel-caption-padding-y:         1.25rem;
$carousel-caption-spacer:            1.25rem;

$carousel-control-icon-width:        2rem;

$carousel-control-prev-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M11.354 1.646a.5.5 0 0 1 0 .708L5.707 8l5.647 5.646a.5.5 0 0 1-.708.708l-6-6a.5.5 0 0 1 0-.708l6-6a.5.5 0 0 1 .708 0z'/></svg>");
$carousel-control-next-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z'/></svg>");

$carousel-transition-duration:       .6s;
$carousel-transition:                transform $carousel-transition-duration ease-in-out; // Define transform transition first if using multiple transitions (e.g., `transform 2s ease, opacity .5s ease-out`)

$carousel-dark-indicator-active-bg:  $black;
$carousel-dark-caption-color:        $black;
$carousel-dark-control-icon-filter:  invert(1) grayscale(100);

Использование

Через атрибуты

Используйте атрибуты данных, чтобы легко контролировать положение карусели. data-bs-slide принимает ключевые слова prev или next, которые изменяют положение слайда относительно его текущего положения. В качестве альтернативы, используйте data-bs-slide-to, чтобы передать необработанный индекс слайда в карусель data-bs-slide-to="2", который сдвигает положение слайда на конкретный индекс, начинающийся с 0.

Атрибут data-bs-ride="carousel" используется для пометки карусели как анимированной, начиная с загрузки страницы. Если Вы не используете data-bs-ride="carousel" для инициализации карусели, Вам придется инициализировать ее самостоятельно. Его нельзя использовать в сочетании с (избыточной и ненужной) явной инициализацией JavaScript той же карусели.

Через JavaScript

Вызов карусели вручную с помощью:

const carousel = new bootstrap.Carousel('#myCarousel')

Опции

Параметры можно передавать через атрибуты данных или JavaScript. Для атрибутов данных добавьте имя параметра к data-bs-, как в data-bs-animation="". Не забудьте изменить тип регистра имени параметра с camelCase на kebab-case при передаче параметров через атрибуты данных. Например, используйте data-bs-custom-class="beautifier" вместо data-bs-customClass="beautifier".

Начиная с Bootstrap 5.2.0, все компоненты поддерживают экспериментальный зарезервированный атрибут данных data-bs-config, который может содержать простую конфигурацию компонента в виде строки JSON. Когда элемент имеет атрибуты data-bs-config='{"delay":0, "title":123}' и data-bs-title="456", окончательное значение title будет 456, а отдельные атрибуты данных переопределяют значения, указанные в data-bs-config. Кроме того, существующие атрибуты данных могут содержать значения JSON, такие как data-bs-delay='{"show":0,"hide":150}'.

Название Тип По умолчанию Описание
interval number 5000 Количество времени задержки между автоматическим циклом элемента. Если false, карусель не будет автоматически циклироваться.
keyboard boolean true Должна ли карусель реагировать на события клавиатуры.
pause string, boolean "hover" Если установлено значение "hover", карусель приостанавливается при нажатии mouseenter и возобновляется при нажатии mouseleave. Если установлено значение false, наведение курсора на карусель не приостанавливает ее. На устройствах с сенсорным экраном, если установлено значение "hover", цикл будет приостанавливаться при touchend (после того, как пользователь завершит взаимодействие с каруселью) на два интервала, а затем автоматически возобновится. Это в дополнение к поведению мыши.
ride string, boolean false Если установлено значение true, автоматически воспроизводится карусель после того, как пользователь вручную прокрутит первый элемент. Если установлено значение "carousel", автоматически воспроизводится карусель при загрузке.
touch boolean true Должна ли карусель поддерживать смахивание влево/вправо на устройствах с сенсорным экраном.
wrap boolean true Должна ли карусель вращаться непрерывно или делать резкие остановки.

Методы

Асинхронные методы и переходы

Все методы API асинхронны и запускают переход. Они возвращаются к вызывающей стороне, как только переход начинается, но до его завершения. Кроме того, вызов метода переходного компонента будет проигнорирован.

Дополнительную информацию см. в нашей документации по JavaScript.

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

const myCarouselElement = document.querySelector('#myCarousel')
const carousel = new bootstrap.Carousel(myCarouselElement, {
  interval: 2000,
  wrap: false
})
Метод Описание
cycle Перебирает элементы карусели слева направо.
pause Запрещает карусели циклически перемещаться по элементам.
prev Переход к предыдущему элементу. Возвращается к вызывающей стороне до того, как был показан предыдущий элемент (например, до того, как произойдет событие slid.bs.carousel).
next Переход к следующему элементу. Возвращается к вызывающей стороне до того, как будет показан следующий элемент (например, до того, как произойдет событие slid.bs.carousel).
nextWhenVisible Не переключайте карусель на следующую, если страница не видна или карусель или ее родитель не видны. Возвращается к вызывающему абоненту до того, как целевой элемент будет показан
to Циклически перемещает карусель к определенному кадру (на основе 0, подобно массиву). Возвращается к вызывающей стороне до того, как целевой элемент будет показан (например, до того, как произойдет событие slid.bs.carousel).
dispose Уничтожает карусель элемента. (Удаляет сохраненные данные в элементе DOM)
getInstance Статический метод, который позволяет вам получить экземпляр карусели, связанный с элементом DOM, вы можете использовать его следующим образом: bootstrap.Carousel.getInstance(element)
getOrCreateInstance Статический метод, который возвращает экземпляр карусели, связанный с элементом DOM, или создает новый, если он не был инициализирован. Вы можете использовать его так: bootstrap.Carousel.getOrCreateInstance(element)

События

Класс карусели Bootstrap предоставляет два события для подключения к функциональности карусели. Оба события имеют следующие дополнительные свойства:

  • direction: Направление, в котором движется карусель (любое "left" или "right").
  • relatedTarget: Элемент DOM, который вставляется на место как активный элемент.
  • from: Индекс текущего элемента.
  • to: Индекс следующего элемента.

Все события карусели запускаются в самой карусели (например, <div class="carousel">).

Тип события Описание
slide.bs.carousel Срабатывает немедленно при вызове метода экземпляра slide.
slid.bs.carousel Запускается, когда карусель завершила переход слайдов.
const myCarousel = document.getElementById('myCarousel')

myCarousel.addEventListener('slide.bs.carousel', event => {
  // сделайте что-нибудь...
})