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的浏览器中,当用户看不到网页时(例如浏览器选项卡处于非活动状态、浏览器窗口最小化等),旋转木马将避免滑动。
prefers-reduced-motion
media query. prefers-reduced-motion
媒体查询。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>
Individual .carousel-item
interval单个.carousel-item
间隔
.carousel-item
intervalAdd 将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
.color
和background-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-duration
Sass变量更改.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
接受关键字prev
或next
,这会改变相对于当前位置的幻灯片位置。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=""
。
interval |
number | 5000 |
false , carousel will not automatically cycle.false ,转盘将不会自动循环。 |
keyboard |
boolean | true |
|
pause |
string | boolean | 'hover' |
|
ride |
string | boolean | false |
'carousel' , autoplays the carousel on load.'carousel' ,则在加载时自动播放旋转木马。 |
wrap |
boolean | true |
|
touch |
boolean | true |
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
})
cycle |
|
pause |
|
prev |
slid.bs.carousel event occurs).slid.bs.carousel 事件发生之前)。 |
next |
slid.bs.carousel event occurs).slid.bs.carousel 事件发生之前)。 |
nextWhenVisible |
|
to |
slid.bs.carousel event occurs).slid.bs.carousel 事件发生之前)。 |
dispose |
|
getInstance
|
bootstrap.Carousel.getInstance(element) |
getOrCreateInstance
|
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">
)上激发。
slide.bs.carousel |
slide instance method is invoked.slide 实例方法时立即激发。 |
slid.bs.carousel |
var myCarousel = document.getElementById('myCarousel')
myCarousel.addEventListener('slide.bs.carousel', function () {
// do something...
})