Skip to main content Skip to docs navigation
View on GitHub

Carousel旋转木马

A slideshow component for cycling through elements—images or slides of text—like a carousel.幻灯片放映组件,用于在元素、图像或文本幻灯片(如旋转木马)之间循环播放。

How it works工作原理

The carousel is a slideshow for cycling through a series of content, built with CSS 3D transforms and a bit of JavaScript. 旋转木马是一个幻灯片,用于循环播放一系列内容,使用CSS 3D转换和一点JavaScript构建。It works with a series of images, text, or custom markup. 它使用一系列图像、文本或自定义标记。It also includes support for previous/next controls and indicators.它还包括对上一个/下一个控件和指示器的支持。

In browsers where the Page Visibility API is supported, the carousel will avoid sliding when the webpage is not visible to the user (such as when the browser tab is inactive, the browser window is minimized, etc.).在支持页面可见性API的浏览器中,当用户看不到网页时(例如浏览器选项卡处于非活动状态、浏览器窗口最小化等),旋转木马将避免滑动。

The animation effect of this component is dependent on the prefers-reduced-motion media query. 此组件的动画效果取决于prefers-reduced-motion媒体查询。See the reduced motion section of our accessibility documentation.请参阅我们的易访问性文档中的简化运动部分

Please be aware that nested carousels are not supported, and carousels are generally not compliant with accessibility standards.请注意,不支持嵌套旋转木马,旋转木马通常不符合可访问性标准。

Example例子

Carousels don’t automatically normalize slide dimensions. 转盘不会自动规格化幻灯片尺寸。As such, you may need to use additional utilities or custom styles to appropriately size content. 因此,您可能需要使用其他实用程序或自定义样式来适当调整内容的大小。While carousels support previous/next controls and indicators, they’re not explicitly required. 虽然转盘支持上一个/下一个控件和指示器,但它们不是明确需要的。Add and customize as you see fit.根据需要添加和定制。

The .active class needs to be added to one of the slides otherwise the carousel will not be visible. 需要将.active类添加到其中一张幻灯片中,否则旋转木马将不可见。Also be sure to set a unique id on the .carousel for optional controls, especially if you’re using multiple carousels on a single page. 还要确保为可选控件在.carousel上设置唯一的id,尤其是在单个页面上使用多个旋转木马时。Control and indicator elements must have a data-bs-target attribute (or href for links) that matches the id of the .carousel element.控件和指示符元素必须具有与.carousel元素id匹配的data-bs-target属性(或链接的href)。

Slides only仅幻灯片

Here’s a carousel with slides only. 这是一个只有幻灯片的旋转木马。Note the presence of the .d-block and .w-100 on carousel images to prevent browser default image alignment.请注意,转盘图像上存在.d-block.w-100,以防止浏览器默认图像对齐。

<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>

With controls带有控件

Adding in the previous and next controls. 添加上一个和下一个控件。We recommend using <button> elements, but you can also use <a> elements with role="button".我们建议使用<button>元素,但也可以使用带有role="button"<a>元素。

<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">Previous</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">Next</span>
</button>
</div>

With indicators带有指示器

You can also add the indicators to the carousel, alongside the controls, too.您还可以将指示器添加到旋转木马,以及控件。

<div id="carouselExampleIndicators" class="carousel slide" data-bs-ride="carousel">
<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">Previous</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">Next</span>
</button>
</div>

With captions带有字幕

Add captions to your slides easily with the .carousel-caption element within any .carousel-item. 在任何.carousel-item内部使用.carousel-caption元素,可以轻松地为幻灯片添加标题。They can be easily hidden on smaller viewports, as shown below, with optional display utilities. 使用可选的显示实用程序,它们可以很容易地隐藏在较小的视口中,如下所示。We hide them initially with .d-none and bring them back on medium-sized devices with .d-md-block.我们最初用.d-none隐藏它们,然后用.d-md-block将它们放回中型设备上。

<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="carousel">
<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>First slide label</h5>
<p>Some representative placeholder content for the first slide.</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>Second slide label</h5>
<p>Some representative placeholder content for the second slide.</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>Third slide label</h5>
<p>Some representative placeholder content for the third slide.</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">Previous</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">Next</span>
</button>
</div>

Crossfade交叉淡入

Add .carousel-fade to your carousel to animate slides with a fade transition instead of a slide..carousel-fade添加到旋转木马中,以使用淡入淡出过渡(而不是幻灯片)设置幻灯片动画。

<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">Previous</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">Next</span>
</button>
</div>

Add data-bs-interval="" to a .carousel-item to change the amount of time to delay between automatically cycling to the next item.data-bs-interval=""添加到.carousel-item更改自动循环到下一个项目之间的延迟时间量。

<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">Previous</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">Next</span>
</button>
</div>

Disable touch swiping禁用触摸刷卡

Carousels support swiping left/right on touchscreen devices to move between slides. 转盘支持在触摸屏设备上向左/向右滑动,以便在幻灯片之间移动。This can be disabled using the data-bs-touch attribute. 这可以使用data-bs-touch属性禁用。The example below also does not include the data-bs-ride attribute and has data-bs-interval="false" so it doesn’t autoplay.下面的示例也不包括data-bs-ride属性,并且具有data-bs-interval="false",所以它不会自动播放。

<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">Previous</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">Next</span>
</button>
</div>

Dark variant暗色变体

Add .carousel-dark to the .carousel for darker controls, indicators, and captions. .carousel-dark添加到.carousel,以获得更暗的控件、指示器和标题。Controls have been inverted from their default white fill with the filter CSS property. 控件已从默认的白色填充反转为filter CSS属性。Captions and controls have additional Sass variables that customize the color and background-color.标题和控件具有自定义colorbackground-color的附加Sass变量。

<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>First slide label</h5>
<p>Some representative placeholder content for the first slide.</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>Second slide label</h5>
<p>Some representative placeholder content for the second slide.</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>Third slide label</h5>
<p>Some representative placeholder content for the third slide.</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">Previous</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">Next</span>
</button>
</div>

Custom transition自定义过渡

The transition duration of .carousel-item can be changed with the $carousel-transition-duration Sass variable before compiling or custom styles if you’re using the compiled CSS. 在编译之前,可以使用$carousel-transition-durationSass变量更改.carousel-item的转换持续时间,如果使用已编译的CSS,则可以使用自定义样式更改.carousel项目的转换持续时间。If multiple transitions are applied, make sure the transform transition is defined first (eg. transition: transform 2s ease, opacity .5s ease-out).如果应用了多个过渡,请确保首先定义变形过渡(例如transition: transform 2s ease, opacity .5s ease-out)。

Sass

Variables变量

$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);

Usage用法

Via data attributes通过data属性

Use data attributes to easily control the position of the carousel. 使用data属性可以轻松控制旋转木马的位置。data-bs-slide accepts the keywords prev or next, which alters the slide position relative to its current position. data-bs-slide接受关键字prevnext,这会改变相对于当前位置的幻灯片位置。Alternatively, use data-bs-slide-to to pass a raw slide index to the carousel data-bs-slide-to="2", which shifts the slide position to a particular index beginning with 0.或者,使用data-bs-slide-to将原始幻灯片索引传递给旋转木马data-bs-slide-to="2",它将滑动位置移动到从0开始的特定索引。

The data-bs-ride="carousel" attribute is used to mark a carousel as animating starting at page load. data-bs-ride="carousel"属性用于将旋转木马标记为从页面加载开始设置动画。If you don’t use data-bs-ride="carousel" to initialize your carousel, you have to initialize it yourself. 如果您不使用data-bs-ride="carousel"来初始化旋转木马,您必须自己初始化它。It cannot be used in combination with (redundant and unnecessary) explicit JavaScript initialization of the same carousel.它不能与同一转盘的显式JavaScript初始化(冗余和不必要)结合使用。

Via 通过JavaScript

Call carousel manually with:通过以下方式手动调用旋转木马:

var myCarousel = document.querySelector('#myCarousel')
var carousel = new bootstrap.Carousel(myCarousel)

Options选项

Options can be passed via data attributes or JavaScript. 选项可以通过数据属性或JavaScript传递。For data attributes, append the option name to data-bs-, as in data-bs-interval="".对于数据属性,将选项名称附加到data-bs-后面,如data-bs-interval=""

Name名称 Type类型 Default默认值 Description描述
interval number 5000 The amount of time to delay between automatically cycling an item. 自动循环项目之间的延迟时间量。If false, carousel will not automatically cycle.如果为false,转盘将不会自动循环。
keyboard boolean true Whether the carousel should react to keyboard events.转盘是否应对键盘事件作出反应。
pause string | boolean 'hover'

If set to 'hover', pauses the cycling of the carousel on mouseenter and resumes the cycling of the carousel on mouseleave. 如果设置为'hover',则在mouseenter上暂停旋转木马的循环,并在mouseleave上恢复旋转木马的循环。If set to false, hovering over the carousel won't pause it.如果设置为false,将鼠标悬停在旋转木马上不会使其暂停。

On touch-enabled devices, when set to 'hover', cycling will pause on touchend (once the user finished interacting with the carousel) for two intervals, before automatically resuming. 在启用触摸功能的设备上,当设置为'hover'时,循环将在touchend上暂停两个间隔(一旦用户完成与旋转木马的交互),然后自动恢复。Note that this is in addition to the above mouse behavior.请注意,这是对上述鼠标行为的补充。

ride string | boolean false Autoplays the carousel after the user manually cycles the first item. 用户手动循环第一个项目后自动播放旋转木马。If set to 'carousel', autoplays the carousel on load.如果设置为'carousel',则在加载时自动播放旋转木马。
wrap boolean true Whether the carousel should cycle continuously or have hard stops.转盘应连续循环还是有硬停止。
touch boolean true Whether the carousel should support left/right swipe interactions on touchscreen devices.转盘是否应支持触摸屏设备上的左/右滑动交互。

Methods方法

Asynchronous methods and transitions异步方法和转换

All API methods are asynchronous and start a transition. 所有API方法都是异步的,并用过渡开始。They return to the caller as soon as the transition is started but before it ends. 转换一开始,但在转换结束之前,它们就返回给调用方。In addition, a method call on a transitioning component will be ignored.此外,对过渡组件的方法调用将被忽略

See our JavaScript documentation for more information.有关更多信息,请参阅我们的JavaScript文档。

You can create a carousel instance with the carousel constructor, for example, to initialize with additional options and start cycling through items:例如,您可以使用旋转木马构造函数创建旋转木马实例,以使用其他选项进行初始化并开始在项目之间循环:

var myCarousel = document.querySelector('#myCarousel')
var carousel = new bootstrap.Carousel(myCarousel, {
interval: 2000,
wrap: false
})
Method方法 Description描述
cycle Cycles through the carousel items from left to right.从左到右循环传送带项目。
pause Stops the carousel from cycling through items.阻止旋转木马在项目之间循环。
prev Cycles to the previous item. 循环到上一项。Returns to the caller before the previous item has been shown在显示上一项之前返回调用方 (e.g., before the slid.bs.carousel event occurs).(例如,在slid.bs.carousel事件发生之前)。
next Cycles to the next item. 循环到下一项。Returns to the caller before the next item has been shown在显示下一项之前返回调用方 (e.g., before the slid.bs.carousel event occurs).(例如,在slid.bs.carousel事件发生之前)。
nextWhenVisible Don't cycle carousel to next when the page isn't visible or the carousel or its parent isn't visible. 当页面不可见或旋转木马或其父对象不可见时,不要将旋转木马循环到下一个。Returns to the caller before the target item has been shown在显示目标项之前返回调用方
to Cycles the carousel to a particular frame (0 based, similar to an array). 将旋转木马循环到特定帧(基于0,类似于数组)。Returns to the caller before the target item has been shown在显示目标项之前返回调用方 (e.g., before the slid.bs.carousel event occurs).(例如,在slid.bs.carousel事件发生之前)。
dispose Destroys an element's carousel. (Removes stored data on the DOM element)破坏元素的旋转木马。(删除存储在DOM元素上的数据)
getInstance Static method which allows you to get the carousel instance associated to a DOM element, you can use it like this: 静态方法,它允许您获取与DOM元素关联的旋转木马实例,您可以这样使用它:bootstrap.Carousel.getInstance(element)
getOrCreateInstance Static method which returns a carousel instance associated to a DOM element or create a new one in case it wasn't initialised.静态方法,该方法返回与DOM元素关联的转盘实例,或者在未初始化的情况下创建一个新实例。 You can use it like this: 您可以这样使用它:bootstrap.Carousel.getOrCreateInstance(element)

Events事件

Bootstrap’s carousel class exposes two events for hooking into carousel functionality. Bootstrap的旋转木马类公开了两个用于挂接到旋转木马功能的事件。Both events have the following additional properties:这两个事件都具有以下附加属性:

  • direction: The direction in which the carousel is sliding (either "left" or "right").:转盘滑动的方向(要么是"left",要么是"right")。
  • relatedTarget: The DOM element that is being slid into place as the active item.:作为活动项滑入到位的DOM元素。
  • from: The index of the current item:当前项目的索引
  • to: The index of the next item:下一项的索引

All carousel events are fired at the carousel itself (i.e. at the <div class="carousel">).所有旋转木马事件都会在旋转木马本身(即在<div class="carousel">)上激发。

Event type事件类型 Description描述
slide.bs.carousel Fires immediately when the slide instance method is invoked.调用slide实例方法时立即激发。
slid.bs.carousel Fired when the carousel has completed its slide transition.旋转木马完成其幻灯片转换时激发。
var myCarousel = document.getElementById('myCarousel')
myCarousel.addEventListener('slide.bs.carousel', function () {
// do something...
})