在 GitHub 上檢視

輪播

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

運作方式

輪播是一個用於循環瀏覽一系列內容的幻燈片，使用 CSS 3D 變形和一些 JavaScript 建立。它適用於一系列圖像、文字或自訂標記。它還支援上一個/下一個控制項和指示器。

在支援 網頁可見度 API 的瀏覽器中，當網頁對使用者不可見（例如瀏覽器分頁處於非活動狀態、瀏覽器視窗已最小化等）時，旋轉木馬會避免滑動。

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

請注意，不支援巢狀旋轉木馬，而旋轉木馬通常不符合無障礙標準。

最後，如果您從原始碼建置我們的 JavaScript，它 需要 util.js。

範例

旋轉木馬不會自動標準化投影片尺寸。因此，您可能需要使用其他工具程式或自訂樣式來適當地調整內容大小。儘管旋轉木馬支援上一個/下一個控制項和指標，但它們並非明確需要。請自行新增並自訂。

必須將 .active 類別新增至其中一個投影片，否則旋轉木馬將不會顯示。另外，請務必在 .carousel 上設定唯一的 id 以供選用控制項，特別是如果在單一頁面上使用多個旋轉木馬時。控制項和指標元素必須具有與 .carousel 元素的 id 相符的 data-target 屬性（或連結的 href）。

僅幻燈片

以下是僅有投影片的旋轉木馬。請注意旋轉木馬影像上的 .d-block 和 .w-100，以防止瀏覽器預設影像對齊。

<div id="carouselExampleSlidesOnly" class="carousel slide" data-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> 元素，但您也可以使用具有 role="button" 的 <a> 元素。

<div id="carouselExampleControls" class="carousel slide" data-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-target="#carouselExampleControls" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleControls" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

帶有指示器

您也可以將指標新增至旋轉木馬，與控制項並列。

<div id="carouselExampleIndicators" class="carousel slide" data-ride="carousel">
  <ol class="carousel-indicators">
    <li data-target="#carouselExampleIndicators" data-slide-to="0" class="active"></li>
    <li data-target="#carouselExampleIndicators" data-slide-to="1"></li>
    <li data-target="#carouselExampleIndicators" data-slide-to="2"></li>
  </ol>
  <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-target="#carouselExampleIndicators" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleIndicators" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

帶有標題

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

<div id="carouselExampleCaptions" class="carousel slide" data-ride="carousel">
  <ol class="carousel-indicators">
    <li data-target="#carouselExampleCaptions" data-slide-to="0" class="active"></li>
    <li data-target="#carouselExampleCaptions" data-slide-to="1"></li>
    <li data-target="#carouselExampleCaptions" data-slide-to="2"></li>
  </ol>
  <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-target="#carouselExampleCaptions" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleCaptions" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

淡入淡出

將 .carousel-fade 加入輪播，以淡入淡出轉場動畫取代滑動轉場。根據輪播內容（例如，只有文字的投影片），您可能需要將 .bg-body 或一些自訂 CSS 加入 .carousel-item，以進行適當的淡入淡出。

<div id="carouselExampleFade" class="carousel slide carousel-fade" data-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-target="#carouselExampleFade" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleFade" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

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

<div id="carouselExampleInterval" class="carousel slide" data-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active" data-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item" data-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-target="#carouselExampleInterval" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleInterval" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

停用觸控滑動

輪播支援在觸控式裝置上左右滑動，以在投影片之間移動。這可以使用 data-touch 屬性停用。以下範例也不包含 data-ride 屬性，且具有 data-interval="false"，因此不會自動播放。

<div id="carouselExampleControlsNoTouching" class="carousel slide" data-touch="false" data-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-target="#carouselExampleControlsNoTouching" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleControlsNoTouching" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

使用方式

透過資料屬性

使用資料屬性輕鬆控制輪播的位置。data-slide 接受關鍵字 prev 或 next，這會根據目前位置變更投影片位置。或者，使用 data-slide-to 將原始投影片索引傳遞給輪播 data-slide-to="2"，這會將投影片位置移至從 0 開始的特定索引。

data-ride="carousel" 屬性用於標記輪播在頁面載入時開始動畫。如果您不使用 data-ride="carousel" 初始化輪播，則必須自行初始化。不能與相同輪播的明確 JavaScript 初始化（多餘且不必要）合併使用。

透過 JavaScript

手動呼叫輪播，使用

$('.carousel').carousel()

選項

選項可以透過資料屬性或 JavaScript 傳遞。對於資料屬性，請將選項名稱附加至 data-，例如 data-interval=""。

名稱 類型 預設值 說明
interval 數字 5000 自動循環項目之間的延遲時間。如果為 false，輪播不會自動循環。
keyboard 布林值 true 輪播是否應對鍵盤事件做出反應。
pause 字串 | 布林值 'hover'

如果設為 'hover'，則在 mouseenter 時暫停輪播循環，並在 mouseleave 時繼續輪播循環。如果設為 false，將滑鼠懸停在輪播上不會暫停輪播。

在觸控式裝置上，如果設為 'hover'，則循環會在 touchend（使用者完成與輪播互動）時暫停兩個間隔，然後自動繼續。請注意，這會額外加上上述滑鼠行為。
ride 字串 false 在使用者手動循環第一個項目後自動播放輪播。如果設為 'carousel'，則在載入時自動播放輪播。
包裝 布林值 true 旋轉木馬是否應持續循環或有硬停頓。
觸摸 布林值 true 旋轉木馬是否應支援觸控螢幕裝置上的左右滑動互動。

方法

非同步方法和過渡

所有 API 方法都是非同步的，並開始過渡。它們在過渡開始後立即返回呼叫者，但在過渡結束前。此外，過渡元件上的方法呼叫將被忽略。

請參閱我們的 JavaScript 文件以取得更多資訊.

.carousel(options)

使用一個選用的選項物件初始化旋轉木馬，並開始循環瀏覽項目。

$('.carousel').carousel({
  interval: 2000
})

.carousel('cycle')

從左到右循環瀏覽旋轉木馬項目。

.carousel('pause')

停止旋轉木馬循環瀏覽項目。

.carousel(number)

將旋轉木馬循環到特定框架（以 0 為基準，類似陣列）。在顯示目標項目之前返回呼叫者（即在發生 slid.bs.carousel 事件之前）。

.carousel('prev')

循環到前一個項目。在顯示前一個項目之前返回呼叫者（即在發生 slid.bs.carousel 事件之前）。

.carousel('next')

循環到下一個項目。在顯示下一個項目之前返回呼叫者（即在發生 slid.bs.carousel 事件之前）。

.carousel('dispose')

銷毀元素的旋轉木馬。

.carousel('nextWhenVisible')

當頁面不可見或旋轉木馬或其父項不可見時，不要將旋轉木馬循環到下一個。在顯示下一個項目之前返回呼叫者（即在發生 slid.bs.carousel 事件之前）。

.carousel('to')

將旋轉木馬循環到特定框架（以 0 為基準，類似陣列）。在顯示下一個項目之前返回呼叫者（即在發生 slid.bs.carousel 事件之前）。

事件

Bootstrap 的旋轉木馬類別公開兩個事件，用於連接到旋轉木馬功能。兩個事件都有下列額外屬性

  • direction：旋轉木馬滑動的方向（"left" 或 "right"）。
  • relatedTarget：作為活動項目滑入的 DOM 元素。
  • from：目前項目的索引
  • to：下一個項目的索引

所有旋轉木馬事件都在旋轉木馬本身觸發（即在 <div class="carousel">）。

事件類型 說明
slide.bs.carousel 當呼叫 slide 執行個體方法時，此事件會立即觸發。
slid.bs.carousel 當旋轉木馬完成其滑動過渡時，此事件會觸發。 
$('#myCarousel').on('slide.bs.carousel', function () {
  // do something...
})

變更轉場持續時間

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