跳到主要內容 跳到文檔導航
Check
in English

旋轉木馬

用於循環播放元素（圖像或文本幻燈片）的幻燈片組件，如輪播。

在本頁面

這個怎麼運作

輪播是一個幻燈片，用於循環瀏覽一系列內容，使用 CSS 3D 轉換和一些 JavaScript 構建。它適用於一系列圖像、文本或自定義標記。它還包括對上一個/下一個控件和指示器的支持。

在支持Page Visibility API的瀏覽器中，當網頁對用戶不可見時（例如瀏覽器選項卡處於非活動狀態、瀏覽器窗口最小化等），輪播將避免滑動。

該組件的動畫效果依賴於 prefers-reduced-motion媒體查詢。請參閱 我們可訪問性文檔的減少運動部分。

請注意，不支持嵌套輪播，並且輪播通常不符合可訪問性標準。

例子

輪播不會自動標準化幻燈片尺寸。因此，您可能需要使用其他實用程序或自定義樣式來適當調整內容的大小。雖然輪播支持上一個/下一個控件和指示器，但它們並不是明確要求的。根據需要添加和自定義。

該類.active需要添加到其中一張幻燈片，否則輪播將不可見。還要確保id在.carousel可選控件上設置唯一性，特別是如果您在單個頁面上使用多個輪播。控件和指示器元素必須具有與元素匹配的data-bs-target屬性（或href用於鏈接）。id.carousel

僅幻燈片

這是一個只有幻燈片的旋轉木馬。請注意輪播圖像上的.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>

帶控件

添加上一個和下一個控件。我們建議使用<button>元素，但您也可以將<a>元素與role="button".

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

有指標

您還可以將指示器與控件一起添加到輪播中。

html 
<div id="carouselExampleIndicators" class="carousel slide" data-bs-ride="true">
  <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-caption任何.carousel-item. 它們可以很容易地隱藏在較小的視口中，如下所示，使用可選的顯示實用程序。我們最初使用隱藏它們，.d-none然後使用.d-md-block.

html 
<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="false">
  <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到您的輪播以使用淡入淡出過渡而不是幻燈片為幻燈片製作動畫。根據您的輪播內容（例如，純文本幻燈片），您可能希望向 s 添加.bg-body或一些自定義 CSS 以.carousel-item進行正確的交叉淡入淡出。

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

添加data-bs-interval=""到 a.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>

禁用觸摸滑動

輪播支持在觸摸屏設備上向左/向右滑動以在幻燈片之間移動。這可以使用data-bs-touch屬性禁用。下面的示例也不包含該data-bs-ride屬性，因此它不會自動播放。

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>

深色變體

添加.carousel-dark到.carousel較暗的控件、指示器和標題。filter控件已使用CSS 屬性從其默認的白色填充反轉。標題和控件有額外的 Sass 變量來自定義color和background-color。

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

自定義過渡

如果您使用已編譯的 CSS ，.carousel-item可以在編譯或自定義樣式之前使用 Sass 變量更改過渡持續時間。$carousel-transition-duration如果應用了多個轉換，請確保首先定義轉換轉換（例如transition: transform 2s ease, opacity .5s ease-out）。

薩斯

變量

所有輪播的變量：

$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接受關鍵字prevor next，它改變相對於當前位置的幻燈片位置。或者，使用data-bs-slide-to將原始幻燈片索引傳遞給 carousel data-bs-slide-to="2"，這會將幻燈片位置移動到以 開頭的特定索引0。

該data-bs-ride="carousel"屬性用於將輪播標記為在頁面加載時開始動畫。如果你不使用data-bs-ride="carousel"初始化你的輪播，你必須自己初始化它。它不能與同一輪播的（冗餘和不必要的）顯式 JavaScript 初始化結合使用。

通過 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並且單獨的數據屬性將覆蓋給定的值 on data-bs-config。此外，現有數據屬性能夠容納 JSON 值，例如data-bs-delay='{"show":0,"hide":150}'.

姓名 類型 默認 描述
interval 數字 5000 自動循環項目之間的延遲時間。
keyboard 布爾值 true 輪播是否應對鍵盤事件做出反應。
pause 字符串，布爾值 "hover" 如果設置為"hover"，則暫停旋轉木馬mouseenter的循環並恢復旋轉木馬的循環mouseleave。如果設置為false，則將鼠標懸停在輪播上不會暫停它。在支持觸摸的設備上，當設置為 時"hover"，循環將暫停touchend（一旦用戶完成與輪播的交互）兩個時間間隔，然後自動恢復。這是對鼠標行為的補充。
ride 字符串，布爾值 false 如果設置為true，則在用戶手動循環第一個項目後自動播放輪播。如果設置為"carousel"，則在加載時自動播放輪播。
touch 布爾值 true 輪播是否應支持觸摸屏設備上的左/右滑動交互。
wrap 布爾值 true 轉盤是否應連續循環或硬停止。

方法

異步方法和轉換

所有 API 方法都是異步的並開始一個轉換。他們在轉換開始但在結束之前立即返回給調用者。此外，過渡組件上的方法調用將被忽略。

有關更多信息，請參閱我們的 JavaScript 文檔。

您可以使用 carousel 構造函數創建一個 carousel 實例，例如，使用其他選項進行初始化並開始循環遍歷項目：

const myCarouselElement = document.querySelector('#myCarousel')
const carousel = new bootstrap.Carousel(myCarouselElement, {
  interval: 2000,
  wrap: 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事件發生之前）返回給調用者。

活動

Bootstrap 的 carousel 類公開了兩個用於連接 carousel 功能的事件。這兩個事件都具有以下附加屬性：

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