輪播（Carousel）

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

On this page

工作原理

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

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

此組件的動畫效果取決于“首選簡化運動媒體”查詢。請參閱我們的可訪問性文檔的簡化運動部分。

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

例子

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

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

僅幻燈片

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

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

帶控件

添加上一個和下一個控件。我們建議使用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上隱藏它們，如下所示，一開始將會用.d-none隱藏，并使用.d-md-block讓它們在中型的設(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加到輪播中，以使用淡入淡出的取代滑動的動畫效果。

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

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

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

<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è)備上左/右滑動以在幻燈片之間移動。這可以使用data-bs-touch屬性禁用。下面的示例既不包括 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>

暗變型

在.carousel上添加.carousel-dark以獲得暗色系的控制項、指示器及字幕。控件已透過CSS屬性filter從它們預(yù)設(shè)的白色充填反轉(zhuǎn)。字幕與控件具有用來自定義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項的轉(zhuǎn)換持續(xù)時間可以在編譯前使用$carousel-transition-duration Sass變量更改，如果使用已編譯的CSS，則可以使用自定義樣式更改。如果應(yī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);

用法

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

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

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

通過JavaScript

使用以下語法手動呼叫輪播：

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

選項

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

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

方法

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

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

See our JavaScript documentation for more information.

例如，您可以使用carousel構(gòu)造函數(shù)創(chuàng)建carousel實例，以使用其他選項進行初始化并開始在項目之間循環(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`	將輪播指向前一個物件。在前一個物件顯示前回傳給調(diào)用者（e.g.，在slid.bs.carousel 事件發(fā)生之前）.
`next`	將輪播指向下一個物件。在后一個物件顯示前回傳給調(diào)用者（e.g.，在slid.bs.carousel 事件發(fā)生之前）.
`nextWhenVisible`	如果頁面或是其父層不可見，就停止將輪播循環(huán)到下一個。在目標(biāo)項目顯示前回傳給調(diào)用者
`to`	將輪播指向特定的索引。（與數(shù)組相同，從0開始）.在目標(biāo)項目顯示前回傳給調(diào)用者（e.g.，在slid.bs.carousel 事件發(fā)生之前）.
`dispose`	銷毀一個元素的輪播。（移除DOM元素上儲存的數(shù)據(jù)）
`getInstance`	允許你取得與DOM元素關(guān)聯(lián)之輪播示例的靜態(tài)方法。

事件

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

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

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

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

var myCarousel = document.getElementById('myCarousel')

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