メインコンテンツへスキップ ドキュメントナビゲーションへスキップ
GitHubで表示

カルーセル

カルーセルのように要素（画像またはテキストのスライド）を順に表示するためのスライドショーコンポーネントです。

このページの内容

仕組み

  • カルーセルは、CSS 3D変換と少しのJavaScriptで構築された、一連のコンテンツを順に表示するためのスライドショーです。画像、テキスト、またはカスタムマークアップの一連のコンテンツで動作します。また、前/次のコントロールとインジケーターもサポートしています。

  • パフォーマンス上の理由から、カルーセルはカルーセルコンストラクタメソッドを使用して手動で初期化する必要があります。初期化しないと、一部のイベントリスナー（特に、タッチ/スワイプサポートに必要なイベント）は、ユーザーが明示的にコントロールまたはインジケーターをアクティブ化するまで登録されません。

    唯一の例外は、data-bs-ride="carousel"属性を持つ自動再生カルーセルです。これらはページ読み込み時に自動的に初期化されます。データ属性を使用して自動再生カルーセルを使用している場合は、コンストラクタメソッドを使用して同じカルーセルを明示的に初期化しないでください。

  • ネストされたカルーセルはサポートされていません。また、一般的にカルーセルはユーザビリティとアクセシビリティの課題を引き起こす可能性があることにも注意してください。

このコンポーネントのアニメーション効果は、prefers-reduced-motionメディアクエリに依存します。アクセシビリティドキュメントのモーション削減セクションを参照してください。

基本的な例

ここに3つのスライドを持つカルーセルの基本的な例を示します。前/次のコントロールに注意してください。<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を設定してください。特に、1つのページで複数のカルーセルを使用している場合はそうです。コントロールとインジケーター要素には、.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オプションで制御できます。Page Visibility APIをサポートするブラウザでは、Webページがユーザーに表示されていない場合（ブラウザタブが非アクティブな場合やブラウザウィンドウが最小化されている場合など）、カルーセルの循環は停止します。

アクセシビリティ上の理由から、自動再生カルーセルの使用は避けることをお勧めします。ページに自動再生カルーセルが含まれている場合は、カルーセルを明示的に一時停止/停止するための追加のボタンまたはコントロールを提供することをお勧めします。

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オプションがcarouselではなくtrueに設定されている場合、カルーセルはページ読み込み時に自動的に循環を開始しません。代わりに、最初のユーザーインタラクションの後でのみ開始されます。

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

コントロールなしの自動再生カルーセル

スライドのみのカルーセルを次に示します。ブラウザのデフォルトの画像配置を防ぐために、カルーセル画像に.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に.carousel-darkを追加します。コントロールは、filter CSSプロパティを使用してデフォルトの白い塗りつぶしと比較して反転します。キャプションとコントロールには、colorとbackground-colorをカスタマイズする追加のSass変数があります。

注意！コンポーネントのダークバリアントは、カラーモードの導入により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>

カスタムトランジション

.carousel-itemのトランジション期間は、コンパイル前またはコンパイル済みのCSSを使用している場合はカスタムスタイルで、$carousel-transition-durationSass変数を使用して変更できます。複数のトランジションが適用されている場合は、トランスフォームトランジションが最初に定義されていることを確認してください（例：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-animation="{value}"のようにオプション名をdata-bs-に追加できます。データ属性を介してオプションを渡す場合は、オプション名のケースタイプを「camelCase」から「kebab-case」に変更してください。たとえば、data-bs-customClass="beautifier"の代わりにdata-bs-custom-class="beautifier"を使用します。

Bootstrap 5.2.0以降、すべてのコンポーネントは、JSON文字列として単純なコンポーネント構成を格納できる実験的な予約済みデータ属性data-bs-configをサポートしています。要素にdata-bs-config='{"delay":0, "title":123}'とdata-bs-title="456"属性がある場合、最終的なtitleの値は456になり、個別のデータ属性はdata-bs-configで指定された値を上書きします。さらに、既存のデータ属性はdata-bs-delay='{"show":0,"hide":150}'のようにJSON値を格納できます。

最終的な構成オブジェクトは、data-bs-config、data-bs-、およびjs objectがマージされた結果であり、最新のキーと値が他を上書きします。

名前 型 デフォルト 説明
interval 数値 5000 アイテムを自動的に切り替える間隔の時間。
keyboard 真偽値 true カルーセルがキーボードイベントに反応するかどうか。
pause 文字列, 真偽値 "hover" "hover" に設定した場合、mouseenter でカルーセルの自動切り替えを一時停止し、mouseleave で自動切り替えを再開します。false に設定した場合、カルーセルにマウスオーバーしても一時停止しません。タッチ対応デバイスでは、"hover" に設定した場合、touchend (ユーザーがカルーセルとのインタラクションを終了した後) で自動切り替えが一時停止し、2つのインターバル後に自動的に再開します。これはマウスの動作に加えて行われます。
ride 文字列, 真偽値 false true に設定した場合、ユーザーが手動で最初のアイテムを切り替えた後、カルーセルの自動再生を開始します。"carousel" に設定した場合、ロード時にカルーセルの自動再生を開始します。
touch 真偽値 true カルーセルがタッチスクリーンデバイスでの左右スワイプ操作をサポートするかどうか。
wrap 真偽値 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 ページ、カルーセル、またはカルーセルの親が表示されていない場合は、次のカルーセルに切り替えないでください。ターゲットアイテムが表示される前に呼び出し元に制御が戻ります。
pause カルーセルがアイテムを切り替えるのを停止します。
prev 前のアイテムに切り替えます。前のアイテムが表示される前（たとえば、slid.bs.carouselイベントが発生する前）に呼び出し元に制御が戻ります。
to カルーセルを特定のフレーム（配列と同様に0ベース）に切り替えます。ターゲットアイテムが表示される前（たとえば、slid.bs.carouselイベントが発生する前）に呼び出し元に制御が戻ります。

イベント

Bootstrapのカルーセルクラスは、カルーセルの機能にフックするための2つのイベントを公開します。両方のイベントには、次の追加プロパティがあります。

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