輪播（Carousel）

一個用於循環瀏覽元素（圖片或文字幻燈片）的幻燈片元件，就像輪播一樣。

本頁內容

運作原理（How it works）

輪播是一個用於循環瀏覽一系列內容的幻燈片，使用 CSS 3D 轉換和一些 JavaScript 建構。它可以處理一系列圖片、文字或自訂標記。它還支援上一張/下一張控制項和指示器。
基於效能考量，輪播必須使用輪播建構函式方法手動初始化。如果沒有初始化，某些事件監聽器（特別是觸控/滑動支援所需的事件）在使用者明確啟用控制項或指示器之前不會被註冊。

唯一的例外是帶有 data-bs-ride="carousel" 屬性的自動播放輪播，因為這些會在頁面載入時自動初始化。如果您使用帶有 data 屬性的自動播放輪播，請不要用建構函式方法明確初始化相同的輪播。
不支援巢狀輪播。您還應該注意，輪播通常可能會導致可用性和無障礙方面的挑戰。

此元件的動畫效果取決於 prefers-reduced-motion 媒體查詢。請參閱我們無障礙文件中的減少動態效果章節。

基本範例（Basic examples）

這是一個包含三張幻燈片的基本輪播範例。請注意上一張/下一張控制項。我們建議使用 <button> 元素，但您也可以使用帶有 role="button" 的 <a> 元素。

html

<div id="carouselExample" class="carousel slide">
  <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="#carouselExample" 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="#carouselExample" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

輪播不會自動標準化幻燈片尺寸。因此，您可能需要使用額外的通用類別或自訂樣式來適當調整內容大小。雖然輪播支援上一張/下一張控制項和指示器，但它們並非必要的。根據需要加入和自訂。

您必須在其中一張幻燈片上加入 .active 類別，否則輪播將不可見。另外，請務必在 .carousel 上設定唯一的 id，特別是當您在單一頁面上使用多個輪播時，這對於選擇性控制項是必要的。控制項和指示器元素必須有一個 data-bs-target 屬性（或連結的 href）與 .carousel 元素的 id 相符。

指示器（Indicators）

您可以在輪播中加入指示器，搭配上一張/下一張控制項。指示器讓使用者可以直接跳到特定幻燈片。

html

<div id="carouselExampleIndicators" class="carousel slide">
  <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>

標題（Captions）

您可以使用任何 .carousel-item 內的 .carousel-caption 元素為幻燈片加入標題。如下所示，它們可以使用選擇性的顯示通用類別在較小的視窗中輕鬆隱藏。我們最初使用 .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.

html

<div id="carouselExampleCaptions" class="carousel slide">
  <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）

在您的輪播上加入 .carousel-fade 以使用淡入淡出過渡效果來切換幻燈片，而非滑動。根據您的輪播內容（例如純文字幻燈片），您可能需要在 .carousel-item 上加入 .bg-body 或一些自訂 CSS 以獲得適當的淡入淡出效果。

html

<div id="carouselExampleFade" class="carousel slide carousel-fade">
  <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>

自動播放輪播（Autoplaying carousels）

您可以透過將 ride 選項設為 carousel 來讓輪播在頁面載入時自動播放。自動播放的輪播會在滑鼠懸停時自動暫停。可以使用 pause 選項控制此行為。在支援 Page Visibility API 的瀏覽器中，當網頁對使用者不可見時（例如瀏覽器分頁處於非活動狀態，或瀏覽器視窗被最小化），輪播會停止循環。

基於無障礙考量，我們建議避免使用自動播放輪播。如果您的頁面確實包含自動播放輪播，我們建議提供一個額外的按鈕或控制項來明確暫停/停止輪播。

請參閱 WCAG 2.2 成功準則 2.2.2 暫停、停止、隱藏。

html

<div id="carouselExampleAutoplaying" 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="#carouselExampleAutoplaying" 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="#carouselExampleAutoplaying" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

當 ride 選項設為 true 而非 carousel 時，輪播不會在頁面載入時自動開始循環。相反地，它只會在第一次使用者互動後開始。

html

<div id="carouselExampleRide" class="carousel slide" data-bs-ride="true">
  <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="#carouselExampleRide" 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="#carouselExampleRide" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

個別 `.carousel-item` 間隔（Individual `.carousel-item` interval）

在 .carousel-item 上加入 data-bs-interval="" 以變更自動循環到下一個項目之間的延遲時間。

html

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

無控制項的自動播放輪播（Autoplaying carousels without controls）

這是一個只有幻燈片的輪播。請注意輪播圖片上的 .d-block 和 .w-100，以防止瀏覽器預設的圖片對齊方式。

html

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

停用觸控滑動（Disable touch swiping）

輪播支援在觸控螢幕裝置上左/右滑動以在幻燈片之間移動。可以透過將 touch 選項設為 false 來停用此功能。

html

<div id="carouselExampleControlsNoTouching" class="carousel slide" data-bs-touch="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）

Deprecated in v5.3.0

在 .carousel 上加入 .carousel-dark 以獲得較深色的控制項、指示器和標題。控制項使用 filter CSS 屬性來反轉，與預設的白色填充相比。標題和控制項有額外的 Sass 變數來自訂 color 和 background-color。

注意！元件的深色變體在 v5.3.0 中隨著色彩模式的引入而被棄用。請不要加入 .carousel-dark，而是在根元素、父容器或元件本身上設定 data-bs-theme="dark"。

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.

html

<div id="carouselExampleDark" class="carousel carousel-dark slide">
  <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）

.carousel-item 的過渡持續時間可以在編譯之前透過 $carousel-transition-duration Sass 變數來變更，或者如果您使用已編譯的 CSS，則可以使用自訂樣式。如果套用多個過渡效果，請確保先定義 transform 過渡效果（例如 transition: transform 2s ease, opacity .5s ease-out）。

CSS

Sass 變數（Sass variables）

所有輪播的變數：

scss/_variables.scss

$carousel-control-color:             $white;
$carousel-control-width:             15%;
$carousel-control-opacity:           .5;
$carousel-control-hover-opacity:     .9;
$carousel-control-transition:        opacity .15s ease;
$carousel-control-icon-filter:       null;

$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 0'/></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-.708'/></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`)

深色輪播的變數：

scss/_variables.scss

$carousel-dark-indicator-active-bg:  $black; // Deprecated in v5.3.4
$carousel-dark-caption-color:        $black; // Deprecated in v5.3.4
$carousel-dark-control-icon-filter:  invert(1) grayscale(100); // Deprecated in v5.3.4

使用方式（Usage）

透過 data 屬性（Via data attributes）

使用 data 屬性輕鬆控制輪播的位置。data-bs-slide 接受關鍵字 prev 或 next，它會根據當前位置改變幻燈片位置。或者，使用 data-bs-slide-to 將原始幻燈片索引傳遞給輪播 data-bs-slide-to="2"，這會將幻燈片位置移動到以 0 開始的特定索引。

透過 JavaScript（Via JavaScript）

手動呼叫輪播：

const carousel = new bootstrap.Carousel('#myCarousel')

選項（Options）

由於選項可以透過 data 屬性或 JavaScript 傳遞，您可以將選項名稱附加到 data-bs-，例如 data-bs-animation="{value}"。透過 data 屬性傳遞選項時，請確保將選項名稱的大小寫類型從「camelCase」更改為「kebab-case」。例如，使用 data-bs-custom-class="beautifier" 而不是 data-bs-customClass="beautifier"。

從 Bootstrap 5.2.0 開始，所有元件都支援實驗性的保留 data 屬性 data-bs-config，可以將簡單的元件配置作為 JSON 字串存放。當元素同時具有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 屬性時，最終的 title 值將是 456，個別的 data 屬性將覆寫 data-bs-config 中給定的值。此外，現有的 data 屬性也能夠存放 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

最終的配置物件是 data-bs-config、data-bs- 和 js object 的合併結果，其中最後給定的鍵值對會覆寫其他的。

名稱	型別	預設值	說明
`interval`	數字	`5000`	自動循環項目之間的延遲時間。
`keyboard`	布林值	`true`	輪播是否應對鍵盤事件做出反應。
`pause`	字串、布林值	`"hover"`	如果設為 `"hover"`，會在 `mouseenter` 時暫停輪播循環，並在 `mouseleave` 時恢復循環。如果設為 `false`，滑鼠懸停在輪播上不會暫停它。在支援觸控的裝置上，當設為 `"hover"` 時，循環會在 `touchend`（使用者完成與輪播互動後）暫停兩個間隔，然後自動恢復。這是除了滑鼠行為之外的額外行為。
`ride`	字串、布林值	`false`	如果設為 `true`，在使用者手動循環第一個項目後自動播放輪播。如果設為 `"carousel"`，在載入時自動播放輪播。
`touch`	布林值	`true`	輪播是否應在觸控螢幕裝置上支援左/右滑動互動。
`wrap`	布林值	`true`	輪播是否應連續循環或有硬性停止。

方法（Methods）

所有 API 方法都是非同步的，並會啟動一個過渡效果。 它們會在過渡開始後立即回傳給呼叫者，但在過渡結束之前。此外，對正在過渡中的元件進行方法呼叫將被忽略。在我們的 JavaScript 文件中了解更多。

您可以使用輪播建構函式建立輪播實例，並傳入任何額外選項。例如，要手動初始化一個自動播放的輪播（假設您沒有在標記本身中使用 data-bs-ride="carousel" 屬性），並設定特定的間隔時間且停用觸控支援，您可以使用：

const myCarouselElement = document.querySelector('#myCarousel')

const carousel = new bootstrap.Carousel(myCarouselElement, {
  interval: 2000,
  touch: false
})

方法	說明
`cycle`	開始從左到右循環輪播項目。
`dispose`	銷毀元素的輪播。（移除儲存在 DOM 元素上的資料）
`getInstance`	靜態方法，允許您取得與 DOM 元素關聯的輪播實例。您可以這樣使用：`bootstrap.Carousel.getInstance(element)`。
`getOrCreateInstance`	靜態方法，返回與 DOM 元素關聯的輪播實例，如果尚未初始化則建立一個新的。您可以這樣使用：`bootstrap.Carousel.getOrCreateInstance(element)`。
`next`	循環到下一個項目。在下一個項目顯示之前返回給呼叫者（例如，在 `slid.bs.carousel` 事件發生之前）。
`nextWhenVisible`	當頁面、輪播或輪播的父元素不可見時，不循環輪播到下一個。在目標項目顯示之前返回給呼叫者。
`pause`	停止輪播循環項目。
`prev`	循環到上一個項目。在上一個項目顯示之前返回給呼叫者（例如，在 `slid.bs.carousel` 事件發生之前）。
`to`	將輪播循環到特定幀（從 0 開始，類似陣列）。在目標項目顯示之前返回給呼叫者（例如，在 `slid.bs.carousel` 事件發生之前）。

事件（Events）

Bootstrap 的輪播類別公開了兩個用於掛接輪播功能的事件。兩個事件都有以下額外屬性：

direction：輪播滑動的方向（"left" 或 "right"）。
relatedTarget：正在滑入成為活動項目的 DOM 元素。
from：當前項目的索引
to：下一個項目的索引

所有輪播事件都在輪播本身觸發（即在 <div class="carousel"> 上）。

事件類型	說明
`slid.bs.carousel`	當輪播完成其幻燈片過渡時觸發。
`slide.bs.carousel`	當呼叫 `slide` 實例方法時立即觸發。

const myCarousel = document.getElementById('myCarousel')

myCarousel.addEventListener('slide.bs.carousel', event => {
  // do something...
})

輪播（Carousel）

運作原理（How it works）

基本範例（Basic examples）

指示器（Indicators）

標題（Captions）

First slide label

Second slide label

Third slide label

淡入淡出（Crossfade）

自動播放輪播（Autoplaying carousels）

個別 .carousel-item 間隔（Individual .carousel-item interval）

無控制項的自動播放輪播（Autoplaying carousels without controls）

停用觸控滑動（Disable touch swiping）

深色變體（Dark variant）

First slide label

Second slide label

Third slide label

自訂過渡效果（Custom transition）

CSS

Sass 變數（Sass variables）

使用方式（Usage）

透過 data 屬性（Via data attributes）

透過 JavaScript（Via JavaScript）

選項（Options）

方法（Methods）

事件（Events）

個別 `.carousel-item` 間隔（Individual `.carousel-item` interval）