輪播（Carousel）

一種幻燈片放映組件，用于在元素、圖像或文本幻燈片（如旋轉(zhuǎn)木馬）之間循環(huán)播放。

On this page

工作原理

carousel是一個(gè)幻燈片，用于循環(huán)播放一系列內(nèi)容，使用css3d轉(zhuǎn)換和一點(diǎn)JavaScript構(gòu)建。它可以處理一系列圖像、文本或自定義標(biāo)記。它還包括對(duì)上一個(gè)/下一個(gè)控件和指示器的支持。

在支持頁(yè)面可見性API的瀏覽器中，當(dāng)用戶看不到網(wǎng)頁(yè)時(shí)（例如瀏覽器選項(xiàng)卡處于非活動(dòng)狀態(tài)、瀏覽器窗口最小化等），輪播將避免滑動(dòng)。

此組件的動(dòng)畫效果取決于“首選簡(jiǎn)化運(yùn)動(dòng)媒體”查詢。請(qǐng)參閱我們的可訪問(wèn)性文檔的簡(jiǎn)化運(yùn)動(dòng)部分。

請(qǐng)注意，不支持嵌套輪播，輪播通常不符合無(wú)障礙標(biāo)準(zhǔn)。

例子

輪播不會(huì)自動(dòng)標(biāo)準(zhǔn)化幻燈片的尺寸。因此，您可能需要使用額外的通用類別或自定義樣式將內(nèi)容調(diào)整成適當(dāng)?shù)拇笮　ｋm然輪播支持上一個(gè)/下一個(gè)控件和指示器，但是它們不是必備項(xiàng)目。可依照需求添加和自定義。

需要將.active添加到其中一個(gè)輪播元素上，否則輪播將不可見。另外一定要在.carousel上為控件元件設(shè)置一個(gè)唯一的id，特別是當(dāng)你在一個(gè)頁(yè)面上使用多個(gè)輪播的時(shí)候。控件和指示器元素必須具有與.carousel元素之id符合的data-bs-target屬性（或是連接的href）。

僅幻燈片

這是一個(gè)只有幻燈片的輪播。請(qǐng)注意在輪播圖片上存在.d-block和.w-100，以避免瀏覽器預(yù)設(shè)的圖象對(duì)齊。

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

帶控件

添加上一個(gè)和下一個(gè)控件。我們建議使用button元素，但也可以將a元素與 role="button"一起使用。.

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

帶指示器

也可以將指示器與控件一起添加到輪播中。

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

帶字幕

在任意.carousel-item中使用.carousel-caption替幻燈片添加字幕。可以選擇使用display通用類別輕易地在較小的viewport上隱藏它們，如下所示，一開始將會(huì)用.d-none隱藏，并使用.d-md-block讓它們?cè)谥行偷脑O(shè)備上重新顯示。

First slide label

Some representative placeholder content for the first slide.

Second slide label

Some representative placeholder content for the second slide.

Third slide label

Some representative placeholder content for the third slide.

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

淡入淡出

將.carousel-fade加到輪播中，以使用淡入淡出的取代滑動(dòng)的動(dòng)畫效果。

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

個(gè)別設(shè)置時(shí)間間隔

在.carousel-item上添加data-bs-interval=""以更改自動(dòng)循環(huán)至下一個(gè)項(xiàng)目的延遲時(shí)間。

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

禁用觸摸切換

輪播組件支持在觸摸屏設(shè)備上左/右滑動(dòng)以在幻燈片之間移動(dòng)。這可以使用data-bs-touch屬性禁用。下面的示例既不包括 data-bs-ride屬性，并且具有data-bs-interval="false" ，因此它不會(huì)自動(dòng)播放。

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

暗變型

在.carousel上添加.carousel-dark以獲得暗色系的控制項(xiàng)、指示器及字幕。控件已透過(guò)CSS屬性filter從它們預(yù)設(shè)的白色充填反轉(zhuǎn)。字幕與控件具有用來(lái)自定義color及background-color的額外Sass變數(shù)。

First slide label

Some representative placeholder content for the first slide.

Second slide label

Some representative placeholder content for the second slide.

Third slide label

Some representative placeholder content for the third slide.

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

自定義轉(zhuǎn)換

.carousel項(xiàng)的轉(zhuǎn)換持續(xù)時(shí)間可以在編譯前使用$carousel-transition-duration Sass變量更改，如果使用已編譯的CSS，則可以使用自定義樣式更改。如果應(yīng)用了多個(gè)變換，請(qǐng)確保首先定義變換變換（例如，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);

用法

通過(guò)數(shù)據(jù)屬性

使用數(shù)據(jù)屬性可以輕松的控制輪播的位置。 data-bs-slide接受prev或next關(guān)鍵字，它們是用來(lái)改變幻燈片的相對(duì)位置（相對(duì)于當(dāng)前位置）。或者，使用data-bs-slide-to將原始幻燈片索引傳遞給data-bs-slide-to="2"，從而將幻燈片位置移動(dòng)到從0開始的特定索引。

當(dāng)頁(yè)面加載的時(shí)候，data-bs-ride=“carousel”屬性會(huì)被用來(lái)標(biāo)記一個(gè)輪播是為動(dòng)態(tài)的。如果不使用data-bs-ride=“carousel”來(lái)初始化輪播，你必須靠自己將其初始化。在同一個(gè)輪播中，data-bs-ride=“carousel”不能與JavaScript初始化同時(shí)使用（多余且不必要）

通過(guò)JavaScript

使用以下語(yǔ)法手動(dòng)呼叫輪播：

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

選項(xiàng)

可以透過(guò)數(shù)據(jù)屬性或JavaScript調(diào)整選項(xiàng)。對(duì)于數(shù)據(jù)屬性，將選項(xiàng)名稱附加到data-bs-，如data-bs-interval=""。

Name	Type	Default	Description
`interval`	number	`5000`	在一個(gè)自動(dòng)循環(huán)的輪播中，項(xiàng)目之間所延遲的時(shí)間。如果為false，輪播不會(huì)自動(dòng)回放。
`keyboard`	boolean	`true`	輪播是否應(yīng)該響應(yīng)鍵盤事件
`pause`	string \| boolean	`'hover'`	如果設(shè)定為“hover”，輪播會(huì)因?yàn)閙ouseenter而暫停﹑并在mouseleave之時(shí)再度執(zhí)行。如果設(shè)定為false，滑入時(shí)將不會(huì)停止輪播。當(dāng)在觸控裝置上設(shè)定為“hover”，則在回放恢復(fù)之前，輪播將會(huì)停止于touchend（直到用戶完成與輪播的互動(dòng)）。請(qǐng)注意，這是上述鼠標(biāo)行為的擴(kuò)充。
`ride`	string \| boolean	`false`	當(dāng)使用者手動(dòng)循環(huán)第一個(gè)元件之后，輪播將自動(dòng)循環(huán)。如果為“輪播”，則在加載后自動(dòng)播放
`wrap`	boolean	`true`	輪播是否應(yīng)該連續(xù)循環(huán)，或是會(huì)停止。
`touch`	boolean	`true`	在觸控裝置上輪播是否支持向左/向右的交互滑動(dòng)。

方法

異步方法和轉(zhuǎn)換

所有API方法都是異步的，并開始轉(zhuǎn)換。轉(zhuǎn)換一開始就返回到調(diào)用方，但在轉(zhuǎn)換結(jié)束之前返回。此外，對(duì)轉(zhuǎn)換組件的方法調(diào)用將被忽略。

See our JavaScript documentation for more information.

例如，您可以使用carousel構(gòu)造函數(shù)創(chuàng)建carousel實(shí)例，以使用其他選項(xiàng)進(jìn)行初始化并開始在項(xiàng)目之間循環(huán)：

var myCarousel = document.querySelector('#myCarousel')
var carousel = new bootstrap.Carousel(myCarousel, {
interval: 2000,
wrap: false
})

Method	Description
`cycle`	由左至右循環(huán)播放
`pause`	將物件的循環(huán)從輪播中停止
`prev`	將輪播指向前一個(gè)物件。在前一個(gè)物件顯示前回傳給調(diào)用者（e.g.，在slid.bs.carousel 事件發(fā)生之前）.
`next`	將輪播指向下一個(gè)物件。在后一個(gè)物件顯示前回傳給調(diào)用者（e.g.，在slid.bs.carousel 事件發(fā)生之前）.
`nextWhenVisible`	如果頁(yè)面或是其父層不可見，就停止將輪播循環(huán)到下一個(gè)。在目標(biāo)項(xiàng)目顯示前回傳給調(diào)用者
`to`	將輪播指向特定的索引。（與數(shù)組相同，從0開始）.在目標(biāo)項(xiàng)目顯示前回傳給調(diào)用者（e.g.，在slid.bs.carousel 事件發(fā)生之前）.
`dispose`	銷毀一個(gè)元素的輪播。（移除DOM元素上儲(chǔ)存的數(shù)據(jù)）
`getInstance`	允許你取得與DOM元素關(guān)聯(lián)之輪播示例的靜態(tài)方法。

事件

Bootstrap提供了兩個(gè)事件給予輪播使用。兩個(gè)事件都具有以下附加屬性：

direction: 輪播滑動(dòng)的方向（“l(fā)eft”或“right”）.
relatedTarget: 被作為啟用的物件的DOM元素。
from: 當(dāng)前物件的索引
to: 下一個(gè)物件的索引

所有輪播事件都在輪播本身（即<div class="carousel">）下被觸發(fā)。

Event type	Description
`slide.bs.carousel`	當(dāng)調(diào)用slide方法時(shí)，此事件會(huì)立即觸發(fā)。
`slid.bs.carousel`	輪播完成切換后，此事件就被觸發(fā)。

var myCarousel = document.getElementById('myCarousel')

myCarousel.addEventListener('slide.bs.carousel', function () {
// do something...
})