syncfusion-react-carousel

Syncfusion React Carousel コンポーネントの実装

目次

• 概要
• はじめに
• アイテムの設定と選択
• ナビゲーションとインジケーター
• アニメーションとトランジション
• API プロパティ
• API メソッド
• API イベント
• スタイルと外観
• アクセシビリティ
• 画像の最適化
• 一般的なパターン
• ユースケース

Syncfusion React Carousel コンポーネントは、自動または手動のトランジションで画像、コンテンツ、その他の連続したアイテムを表示できる、強力で多機能なカルーセルです。複数のアニメーション効果、カスタマイズ可能なインジケーターとナビゲーター、キーボードナビゲーション、包括的なアクセシビリティ機能をサポートしています。

このスキルを使用する場面

次のような場合に Carousel コンポーネントを実装してください。

• スムーズなトランジションを備えた、切り替わる画像ギャラリーを作成する
• ナビゲーションコントロール付きのスライドショーを構築する
• EC サイトで商品カルーセルを表示する
• インジケーター付きのユーザーレビュー用スライダーを実装する
• 自動再生機能を備えたコンテンツカルーセルを構築する
• モバイルデバイスでのタッチ／スワイプナビゲーションをサポートする
• アクセシビリティ要件に準拠してアイテムを表示する（WCAG 2.2、Section 508）

コンポーネントの概要

Carousel コンポーネントが管理する内容は次のとおりです。

• ビジュアル表示： カスタマイズ可能なテンプレートを使用して、アクティブなスライドを 1 つ表示します
• ナビゲーション： 複数の表示モードに対応した前へ／次へボタン
• インジケーター： 複数のインジケータータイプ（ドット、分数、プログレスバー）で現在の位置を表示します
• アニメーション： フェード、スライド、カスタム効果によるスムーズなスライドトランジション
• 操作： 自動再生、手動スワイプ、キーボードナビゲーション
• アクセシビリティ： 完全な ARIA サポート、キーボードショートカット、スクリーンリーダーへの対応

コアインポート：

import { CarouselComponent, CarouselItemsDirective, CarouselItemDirective } from "@syncfusion/ej2-react-navigations";

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• インストールとパッケージの依存関係
• Vite または Create React App を使用した開発環境のセットアップ
• CSS のインポートとテーマの設定（Tailwind、Bootstrap、Fluent、Material）
• 基本的なカルーセルコンポーネントのセットアップ
• アイテムを使った最初の動作例
• よくあるセットアップの問題と解決策

参照する場面： Carousel を初めてセットアップするとき、または初期設定の問題を解決するとき。

アイテムの設定と選択

📄 参照： references/populating-items.md

• CarouselItem ディレクティブを使用したスライドの設定
• itemTemplate を使用したデータソースのバインド
• selectedIndex を使用した初期スライドの設定
• prev() および next() メソッドによるナビゲーション
• 部分的に表示されるスライド（隣接するスライドの表示）
• プログラムによるスライド描画と宣言的なスライド描画

参照する場面： スライドコンテンツの作成、動的データの処理、ナビゲーションコントロールの実装を行うとき。

ナビゲーターとインジケーター

📄 参照： references/navigators-and-indicators.md

• 前へ／次へナビゲーターボタンの表示モード
• カスタムナビゲーターボタンのテンプレート
• インジケーター（プログレスドット）の表示／非表示
• 4 種類のインジケータータイプ：Default、Dynamic、Fraction、Progress
• プレビュー画像付きのインジケーターテンプレート
• 再生／一時停止ボタンのコントロールとテンプレート

参照する場面： ナビゲーション UI のカスタマイズ、インジケーターのスタイル変更、再生コントロールの実装を行うとき。

アニメーションとトランジション

📄 参照： references/animations-and-transitions.md

• アニメーション効果（フェード、スライド、カスタム CSS）
• アイテムごとのスライドトランジション間隔の設定
• 自動再生の構成とタイミング
• ホバー時の一時停止動作
• ループ再生と非ループ再生の動作
• タッチスワイプモードと操作の無効化
• スライド変更イベント（slideChanging、slideChanged）

読むタイミング： スムーズなトランジションの実装、自動再生の構成、またはカスタムアニメーションの追加を行う場合。

スタイルと外観

📄 参照： references/styling-and-appearance.md

• カスタマイズ用の CSS クラス構造
• インジケーターの外観と間隔のカスタマイズ
• ナビゲーターボタンの配置とスタイル設定
• 部分スライド領域のカスタマイズ
• ビジュアルテーマ設定のための Theme Studio との統合
• ダークモードとカスタムカラースキーム

読むタイミング： インジケーターやナビゲーターのスタイル設定、要素の配置、またはカスタムテーマの作成を行う場合。

アクセシビリティ

📄 参照： references/accessibility.md

• WCAG 2.2 および Section 508 への準拠
• ARIA 属性とロール
• キーボード操作のショートカット（矢印、Home、End、Space、Enter）
• スクリーンリーダーのサポート
• フォーカス管理とモバイルアクセシビリティ

読むタイミング： アクセシブルなカルーセルの構築や、キーボードナビゲーションの実装を行う場合。

画像の最適化

📄 参照： references/image-optimization.md

• カルーセル画像を WebP 形式で読み込む
• パフォーマンス向上とファイルサイズの削減
• 画像形式の変換手法
• カルーセルアイテムを使った実装

読むタイミング： カルーセルのパフォーマンス最適化や、最新の画像形式の実装を行う場合。

クイックスタートの例

5 枚の画像を使った最小構成の動作するカルーセル：

import { CarouselComponent, CarouselItemsDirective, CarouselItemDirective } from "@syncfusion/ej2-react-navigations";
import * as React from "react";

const App = () => {
  return (
    <div className='control-container'>
      <CarouselComponent>
        <CarouselItemsDirective>
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="cardinal" style="height:100%;width:100%;" /><figcaption class="img-caption">Cardinal</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="kingfisher" style="height:100%;width:100%;" /><figcaption class="img-caption">Kingfisher</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="toucan" style="height:100%;width:100%;" /><figcaption class="img-caption">Toucan</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="warbler" style="height:100%;width:100%;" /><figcaption class="img-caption">Warbler</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="bee-eater" style="height:100%;width:100%;" /><figcaption class="img-caption">Bee-eater</figcaption></figure>' />
        </CarouselItemsDirective>
      </CarouselComponent>
    </div>
  );
}

export default App;

よくあるパターン

パターン 1：インジケーターとナビゲーターを備えた自動再生ギャラリー

<CarouselComponent autoPlay={true} showIndicators={true} buttonsVisibility="Visible">
  <CarouselItemsDirective>
    {/* items */}
  </CarouselItemsDirective>
</CarouselComponent>

パターン 2：動的コンテンツを使ったデータ駆動型カルーセル

const itemTemplate = (props: any): JSX.Element => {
  return <img src={props.imageUrl} alt={props.title} />;
}

<CarouselComponent dataSource={carouselData} itemTemplate={itemTemplate} />

パターン 3：カスタムナビゲーションボタンを備えたカルーセル

const nextButtonTemplate = (props: any): JSX.Element => {
  return <ButtonComponent iconCss="e-icons e-chevron-right" />;
}

<CarouselComponent nextButtonTemplate={nextButtonTemplate} />

パターン 4：タッチ操作に対応したモバイルカルーセル

<CarouselComponent 
  enableTouchSwipe={true} 
  swipeMode={CarouselSwipeMode.Touch & CarouselSwipeMode.Mouse}
  pauseOnHover={true}
>
  {/* items */}
</CarouselComponent>

API プロパティの概要

コア表示プロパティ：

• dataSource - カルーセルを外部データにバインドします
• itemTemplate - データバインドされたアイテムのテンプレート
• items - CarouselItemModel のコレクション
• selectedIndex - 現在のスライドインデックス

アニメーションと動作：

• animationEffect - アニメーションの種類（None、Slide、Fade、Custom）
• interval - トランジションの遅延時間（ミリ秒、既定値：5000）
• autoPlay - 自動再生を有効にします（既定値：false）
• loop - スライドを無限にループ再生します（既定値：true）
• pauseOnHover - ホバー時に一時停止します（既定値：true）
• enableTouchSwipe - タッチスワイプを有効にします（既定値：true）
• swipeMode - タッチ／マウスのスワイプモード（Touch、Mouse）

UI コントロール：

• buttonsVisibility - ナビゲーターボタン（Hidden、Visible、VisibleOnHover）
• showIndicators - インジケーターを表示します（既定値：true）
• showPlayButton - 再生／一時停止ボタンを表示します（既定値：false）
• indicatorsType - インジケーターのスタイル（Default、Dynamic、Fraction、Progress）

カスタマイズ：

• previousButtonTemplate - 前へボタンの UI
• nextButtonTemplate - 次へボタンの UI
• playButtonTemplate - 再生／一時停止ボタンの UI
• indicatorsTemplate - インジケーターの UI
• cssClass - カスタム CSS クラス
• partialVisible - 隣接するスライドを表示します（既定値：false）
• allowKeyboardInteraction - キーボードナビゲーション（既定値：true）

レイアウトとローカライズ：

• height - コンポーネントの高さ（ピクセル／パーセンテージ）
• width - コンポーネントの幅（ピクセル／パーセンテージ）
• enableRtl - 右から左への表示をサポートします
• enablePersistence - 再読み込み後も状態を保持します
• locale - カルチャ／ローカライズの設定
• htmlAttributes - カスタム HTML 属性

一般的なユースケース

1. 商品ギャラリー（Eコマース）

• フェードアニメーションで商品画像を表示
• 利用可能な画像を示すインジケーターを表示
• モバイルユーザーがスワイプできるようにする
• 参照：populating-items.md + animations-and-transitions.md

2. お客様の声／レビューカルーセル

• 10秒間隔でお客様の声を自動再生
• カスタムのお客様の声テンプレート
• 読みやすいようにホバー時に一時停止
• 参照：populating-items.md + animations-and-transitions.md

3. アクセシブルなバナーカルーセル

• Home／End／矢印キーによるキーボードナビゲーション
• WCAG 2.2 準拠の構造
• スクリーンリーダーに対応したラベル
• 参照：accessibility.md

4. スタイル設定されたヒーローカルーセル

• ナビゲーターとインジケーターのスタイルをカスタマイズ
• コンテキストを伝える部分表示スライド
• Theme Studio によるカスタマイズ
• 参照：styling-and-appearance.md + navigators-and-indicators.md

5. データ連携カルーセル

• カルーセルを REST API のデータにバインド
• アイテムのプロパティに基づく動的テンプレート
• リアルタイム更新
• 参照：populating-items.md

API リファレンス全編

API プロパティのリファレンス

📄 参照： references/api-properties.md

機能別に整理された、28 個以上のカルーセルプロパティに関する包括的なドキュメントです。

• コアデータと選択： dataSource、itemTemplate、items、selectedIndex
• アニメーションとタイミング： animationEffect、interval、autoPlay、loop、pauseOnHover
• ナビゲーションとインジケーター： buttonsVisibility、showIndicators、indicatorsType、showPlayButton
• テンプレートとカスタマイズ： ボタン／インジケーターのテンプレート、cssClass、partialVisible
• 操作とアクセシビリティ： enableTouchSwipe、swipeMode、allowKeyboardInteraction
• レイアウトとローカライズ： height、width、enableRtl、enablePersistence、locale、htmlAttributes

各プロパティには、型情報、デフォルト値、実用的なコード例が含まれています。

API メソッドのリファレンス

📄 参照： references/api-methods.md

すべてのカルーセル制御メソッドに関する完全なドキュメントです。

• next() - ループに対応した次のスライドへの移動
• prev() - ループに対応した前のスライドへの移動
• getHostElement() - 基になるカルーセルの DOM 要素へのアクセス

メソッドのシグネチャ、ユースケース、実用的な例に加えて、複数のスライドをスキップする、特定のスライドに移動する、カルーセルまでスクロールするといった高度なパターンも含まれています。

API イベントのリファレンス

📄 参照： references/api-events.md

イベント引数の全項目を含む、包括的なイベントドキュメントです。

• slideChanging - 遷移の前に発生します（キャンセル可能）

  • 引数：cancel、currentIndex、currentSlide、nextIndex、nextSlide、isSwiped、name、slideDirection
  • ユースケース：検証、確認ダイアログ、特定のスライドへのアクセス防止

• slideChanged - 遷移の後に発生します（キャンセル不可）

  • 引数：currentIndex、currentSlide、previousIndex、previousSlide、isSwiped、name、slideDirection
  • ユースケース：分析の追跡、UI カウンターの更新、コンテンツの読み込み、アニメーションのトリガー

レート制限、履歴の追跡、分析の統合、イベントパターンライブラリに関する実用的な例も含まれています。

次のステップ

1. まずはこちら: getting-started.mdを読んで、インストールと設定を行います
2. コンテンツを追加: populating-items.mdに従って、データを追加します
3. UI をカスタマイズ: navigators-and-indicators.mdを使って、コントロールを設定します
4. 動作を強化: animations-and-transitions.mdを参考に、エフェクトを追加します
5. デザインを仕上げる: styling-and-appearance.mdを適用して、スタイルを調整します
6. アクセシビリティを確保: accessibility.mdを実装して、コンプライアンスに対応します
7. 画像を最適化: image-optimization.mdを使って、パフォーマンスを向上させます