GitHub で表示

カルーセル

画像やテキストのスライドなど、要素をカルーセルのように循環させるためのスライドショーコンポーネント。

仕組み

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

Page Visibility API がサポートされているブラウザでは、Web ページがユーザーに表示されていない場合 (ブラウザのタブが非アクティブになっている場合、ブラウザのウィンドウが最小化されている場合など)、カルーセルはスライドを回避します。

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

ネストされたカルーセルはサポートされておらず、カルーセルは一般にアクセシビリティ標準に準拠していないことに注意してください。

最後に、ソースから JavaScript を構築している場合は、util.js が必要です。

例

カルーセルは、スライドの寸法を自動的に正規化しません。そのため、コンテンツのサイズを適切に設定するために、追加のユーティリティやカスタムスタイルを使用する必要がある場合があります。カルーセルは前/次コントロールとインジケーターをサポートしていますが、明示的に必須ではありません。必要に応じて追加およびカスタマイズしてください。

.active クラスをスライドの1つに追加する必要があります。そうしないと、カルーセルが表示されません。また、オプションのコントロール用に .carousel に一意の id を設定してください。特に、1つのページで複数のカルーセルを使用している場合はなおさらです。コントロールとインジケーターの要素には、.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 で中サイズのデバイスで復元します。

最初のスライドのラベル

最初のスライドの代表的なプレースホルダーコンテンツ。

2番目のスライドのラベル

2番目のスライドの代表的なプレースホルダーコンテンツ。

3番目のスライドのラベル

3番目のスライドの代表的なプレースホルダーコンテンツ。

<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 を追加して、スライドではなくフェードトランジションでスライドをアニメーション化します。カルーセルのコンテンツ (テキストのみのスライドなど) によっては、適切なクロスフェードのために、.carousel-item に .bg-body またはカスタム CSS を追加する必要がある場合があります。

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

個々の `.carousel-item` の間隔

次の項目に自動的に切り替わるまでの遅延時間を変更するには、.carousel-item に data-interval="" を追加します。

<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` (ユーザーがカルーセルとの対話を終了したとき) で循環が一時停止し、2つの間隔の後、自動的に再開します。これは、上記のマウスの動作に加えて行われることに注意してください。
ride	文字列	false	ユーザーが最初の項目を手動で循環させた後、カルーセルを自動再生します。`'carousel'` に設定すると、読み込み時にカルーセルが自動再生されます。
wrap	ブール値	true	カルーセルを連続的に循環させるか、ハードストップを設定するかどうか。
touch	ブール値	true	カルーセルがタッチスクリーンデバイスでの左右のスワイプ操作をサポートするかどうか。

メソッド

非同期メソッドとトランジション

すべての API メソッドは 非同期 であり、トランジション を開始します。それらは、トランジションが開始されるとすぐに、終了する前 に呼び出し元に戻ります。さらに、トランジション中のコンポーネントに対するメソッド呼び出しは無視されます。

詳細については、JavaScript ドキュメントを参照してください.

`.carousel(options)`

オプションの object を使用してカルーセルを初期化し、項目を循環させ始めます。

$('.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 のカルーセルクラスは、カルーセル機能をフックするための2つのイベントを公開します。両方のイベントには、次の追加のプロパティがあります。

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