跳到主要內容 跳到文件瀏覽
在 GitHub 上檢視

旋轉木馬

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

在此頁面上

運作方式

  • 輪播是一個幻燈片，用於循環播放一系列內容，並使用 CSS 3D 轉換和一些 JavaScript 構建。它可以處理一系列圖片、文字或自訂標記。它還支援上一個/下一個控制項和指示器。

  • 基於效能考量，旋轉木馬必須使用 旋轉木馬建構函式方法 手動初始化。未初始化時，某些事件監聽器（特別是需要觸控/滑動支援的事件）將不會在使用者明確啟用控制項或指標之前註冊。

    唯一的例外是具有 data-bs-ride="carousel" 屬性的 自動播放旋轉木馬，因為這些旋轉木馬會在載入頁面時自動初始化。如果你使用具有資料屬性的自動播放旋轉木馬，請勿使用建構函式方法明確初始化相同的旋轉木馬。

  • 不支援巢狀旋轉木馬。你也應該知道，旋轉木馬通常會造成可用性和可存取性方面的挑戰。

此元件的動畫效果依賴於 prefers-reduced-motion 媒體查詢。請參閱 無障礙文件中的減少動作區段。

基本範例

以下是包含三張投影片的基本旋轉木馬範例。請注意上一個/下一個控制項。我們建議使用 <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 以供選用控制項，特別是如果您在單一頁面上使用多個走馬燈時。控制項和指標元素必須具有與 .carousel 元素的 id 相符的 data-bs-target 屬性（或連結的 href）。

指標

您可以將指標新增到走馬燈，以及上一個/下一個控制項。指標讓使用者可以直接跳到特定投影片。

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>

標題

您可以使用任何 .carousel-item 中的 .carousel-caption 元素，為投影片新增標題。它們可以輕鬆隱藏在較小的視窗中，如下所示，並搭配選用的 顯示工具。我們最初使用 .d-none 隱藏它們，並使用 .d-md-block 在中型裝置上顯示它們。

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>

淡入淡出

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

自動播放走馬燈

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

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

請參閱 WCAG 2.1 成功準則 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>

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

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>

沒有控制項的自動播放輪播

以下是一個僅有投影片的輪播。請注意輪播圖片上存在 .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>

停用觸控滑動

輪播支援在觸控式螢幕裝置上左右滑動以在投影片之間移動。這項功能可以透過將 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>

深色變體

已於 v5.3.0 中棄用

將 .carousel-dark 加入 .carousel 以取得較深的控制項、指標和標題。控制項會與其預設白色填滿反轉，並使用 filter CSS 屬性。標題和控制項有額外的 Sass 變數，可自訂 color 和 background-color。

注意！元件的深色變體已於 v5.3.0 中棄用，並改為使用色彩模式。請勿再加入 .carousel-dark，而是在根元素、父層包裝或元件本身設定 data-bs-theme="dark"。

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>

自訂轉場

如果使用已編譯的 CSS，可以在編譯前使用 Sass 變數 $carousel-transition-duration 變更 .carousel-item 的轉場持續時間，或使用自訂樣式。如果套用多個轉場，請確定變形轉場已定義在最前面（例如 transition: transform 2s ease, opacity .5s ease-out）。

CSS

Sass 變數

所有輪播的變數

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

深色輪播 的變數

scss/_variables.scss 
$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 開始。

透過 JavaScript

手動呼叫輪播，使用

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

選項

由於選項可以透過資料屬性或 JavaScript 傳遞，您可以將選項名稱附加到 data-bs-，例如 data-bs-animation="{value}"。透過資料屬性傳遞選項時，請務必將選項名稱的類型從「camelCase」變更為「kebab-case」。例如，使用 data-bs-custom-class="beautifier"，而非 data-bs-customClass="beautifier"。

從 Bootstrap 5.2.0 開始，所有元件都支援一個實驗性保留資料屬性 data-bs-config，它可以將簡單元件組態作為 JSON 字串存放。當一個元素具有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 屬性時，最後的 title 值將會是 456，而個別資料屬性將會覆寫 data-bs-config 中提供的數值。此外，現有的資料屬性可以存放 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

最後的組態物件是 data-bs-config、data-bs- 和 js 物件 的合併結果，其中最新提供的鍵值會覆寫其他鍵值。

名稱 類型 預設值 說明
間隔 數字 5000 自動循環項目之間的延遲時間。
鍵盤 布林值 true 旋轉木馬是否應對鍵盤事件做出反應。
暫停 字串、布林值 "hover" 如果設定為 "hover"，則在 mouseenter 上暫停旋轉木馬的循環，並在 mouseleave 上恢復旋轉木馬的循環。如果設定為 false，則將滑鼠懸停在旋轉木馬上不會暫停旋轉木馬。在觸控式裝置上，如果設定為 "hover"，則循環將在 touchend (使用者完成與旋轉木馬互動後) 暫停兩個間隔，然後自動恢復。這是除了滑鼠行為之外的行為。
騎乘 字串、布林值 false 如果設定為 true，則在使用者手動循環第一個項目後自動播放旋轉木馬。如果設定為 "carousel"，則在載入時自動播放旋轉木馬。
觸控 布林值 true 旋轉木馬是否應支援觸控式螢幕裝置上的左右滑動互動。
包裝 布林值 true 旋轉木馬應連續循環還是強制停止。

方法

所有 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 當頁面、輪播或輪播的父項不可見時，不要將輪播循環到下一個。在顯示目標項目之前傳回呼叫者。
暫停 停止輪播循環項目。
prev 循環到前一個項目。在顯示前一個項目之前傳回呼叫者（例如，在發生 slid.bs.carousel 事件之前）。
to 將輪播循環到特定畫面（從 0 開始，類似陣列）。在顯示目標項目之前傳回呼叫者（例如，在發生 slid.bs.carousel 事件之前）。

事件

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...
})