輪播（Carousel）
一種幻燈片放映組件，用于在元素、圖像或文本幻燈片（如旋轉木馬）之間循環播放。
On this page
工作原理
carousel是一個幻燈片，用于循環播放一系列內容，使用css3d轉換和一點JavaScript構建。它可以處理一系列圖像、文本或自定義標記。它還包括對上一個/下一個控件和指示器的支持。
在支持頁面可見性API的瀏覽器中，當用戶看不到網頁時（例如瀏覽器選項卡處于非活動狀態、瀏覽器窗口最小化等），輪播將避免滑動。
此組件的動畫效果取決于“首選簡化運動媒體”查詢。請參閱我們的可訪問性文檔的簡化運動部分。
請注意，不支持嵌套輪播，輪播通常不符合無障礙標準。
例子
輪播不會自動標準化幻燈片的尺寸。因此，您可能需要使用額外的通用類別或自定義樣式將內容調整成適當的大小。雖然輪播支持上一個/下一個控件和指示器，但是它們不是必備項目。可依照需求添加和自定義。
需要將.active添加到其中一個輪播元素上，否則輪播將不可見。另外一定要在.carousel上為控件元件設置一個唯一的id，特別是當你在一個頁面上使用多個輪播的時候。控件和指示器元素必須具有與.carousel元素之id符合的data-bs-target屬性（或是連接的href）。
僅幻燈片
這是一個只有幻燈片的輪播。請注意在輪播圖片上存在.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>帶控件
添加上一個和下一個控件。我們建議使用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讓它們在中型的設備上重新顯示。
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>個別設置時間間隔
在.carousel-item上添加data-bs-interval=""以更改自動循環至下一個項目的延遲時間。
<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>禁用觸摸切換
輪播組件支持在觸摸屏設備上左/右滑動以在幻燈片之間移動。這可以使用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從它們預設的白色充填反轉。字幕與控件具有用來自定義color及background-color的額外Sass變數。
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>自定義轉換
.carousel項的轉換持續時間可以在編譯前使用$carousel-transition-duration Sass變量更改，如果使用已編譯的CSS，則可以使用自定義樣式更改。如果應用了多個變換，請確保首先定義變換變換（例如，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);
用法
通過數據屬性
使用數據屬性可以輕松的控制輪播的位置。 data-bs-slide接受prev或next關鍵字，它們是用來改變幻燈片的相對位置（相對于當前位置）。或者，使用data-bs-slide-to將原始幻燈片索引傳遞給data-bs-slide-to="2"，從而將幻燈片位置移動到從0開始的特定索引。
當頁面加載的時候，data-bs-ride=“carousel”屬性會被用來標記一個輪播是為動態的。如果不使用data-bs-ride=“carousel”來初始化輪播，你必須靠自己將其初始化。在同一個輪播中，data-bs-ride=“carousel”不能與JavaScript初始化同時使用（多余且不必要）
通過JavaScript
使用以下語法手動呼叫輪播：
var myCarousel = document.querySelector('#myCarousel')
var carousel = new bootstrap.Carousel(myCarousel)
選項
可以透過數據屬性或JavaScript調整選項。對于數據屬性，將選項名稱附加到data-bs-，如data-bs-interval=""。
| Name | Type | Default | Description |
|---|---|---|---|
interval |
number | 5000 |
在一個自動循環的輪播中，項目之間所延遲的時間。如果為false，輪播不會自動回放。 |
keyboard |
boolean | true |
輪播是否應該響應鍵盤事件 |
pause |
string | boolean | 'hover' |
如果設定為“hover”，輪播會因為mouseenter而暫停﹑并在mouseleave之時再度執行。如果設定為false，滑入時將不會停止輪播。 當在觸控裝置上設定為“hover”，則在回放恢復之前，輪播將會停止于touchend（直到用戶完成與輪播的互動）。請注意，這是上述鼠標行為的擴充。 |
ride |
string | boolean | false |
當使用者手動循環第一個元件之后，輪播將自動循環。如果為“輪播”，則在加載后自動播放 |
wrap |
boolean | true |
輪播是否應該連續循環，或是會停止。 |
touch |
boolean | true |
在觸控裝置上輪播是否支持向左/向右的交互滑動。 |
方法
異步方法和轉換
所有API方法都是異步的，并開始轉換。轉換一開始就返回到調用方，但在轉換結束之前返回。此外，對轉換組件的方法調用將被忽略。
例如，您可以使用carousel構造函數創建carousel實例，以使用其他選項進行初始化并開始在項目之間循環：
var myCarousel = document.querySelector('#myCarousel')
var carousel = new bootstrap.Carousel(myCarousel, {
interval: 2000,
wrap: false
})
| Method | Description |
|---|---|
cycle |
由左至右循環播放 |
pause |
將物件的循環從輪播中停止 |
prev |
將輪播指向前一個物件。在前一個物件顯示前回傳給調用者（e.g.，在slid.bs.carousel 事件發生之前）. |
next |
將輪播指向下一個物件。在后一個物件顯示前回傳給調用者（e.g.，在slid.bs.carousel 事件發生之前）. |
nextWhenVisible |
如果頁面或是其父層不可見，就停止將輪播循環到下一個。在目標項目顯示前回傳給調用者 |
to |
將輪播指向特定的索引。（與數組相同，從0開始）.在目標項目顯示前回傳給調用者（e.g.，在slid.bs.carousel 事件發生之前）. |
dispose |
銷毀一個元素的輪播。（移除DOM元素上儲存的數據） |
getInstance |
允許你取得與DOM元素關聯之輪播示例的靜態方法。 |
事件
Bootstrap提供了兩個事件給予輪播使用。兩個事件都具有以下附加屬性：
direction: 輪播滑動的方向（“left”或“right”）.relatedTarget: 被作為啟用的物件的DOM元素。from: 當前物件的索引to: 下一個物件的索引
所有輪播事件都在輪播本身（即<div class="carousel">）下被觸發。
| Event type | Description |
|---|---|
slide.bs.carousel |
當調用slide方法時，此事件會立即觸發。 |
slid.bs.carousel |
輪播完成切換后，此事件就被觸發。 |
var myCarousel = document.getElementById('myCarousel')
myCarousel.addEventListener('slide.bs.carousel', function () {
// do something...
})