syncfusion-blazor-carousel

Syncfusion Blazor Carousel

Syncfusion Blazor Carousel コンポーネントを実装するための包括的なガイドです。ナビゲーションコントロール、インジケーター、アニメーション効果を使って、画像、テキスト、またはカスタムコンテンツを順番に表示するインタラクティブなスライドショーを作成できます。

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

ユーザーが次のことを行う必要がある場合に、このスキルを使用します。

• 画像ギャラリーや写真カルーセルを作成する
• 複数のアイテムを表示する製品紹介スライダーを構築する
• 自動切り替えによるコンテンツのローテーションを実装する
• ナビゲーションコントロール付きのスライドショーを作成する
• ローテーションするバナーやヒーローセクションを作成する
• お客様の声やレビューをスライド形式で表示する
• 一部を表示するスライドレイアウト（前後のアイテムを表示）を構築する
• キーボードナビゲーションに対応したアクセシブルなカルーセルを実装する
• アニメーションでスライド切り替えをカスタマイズする
• スライドの自動切り替え用に再生／一時停止コントロールを追加する

コンポーネントの概要

Syncfusion Blazor Carousel は、アイテムのコレクションを循環して閲覧できるナビゲーションコンポーネントです。次の機能をサポートしています。

• 複数のアニメーション効果： スライド、フェード、またはカスタム CSS アニメーション
• ナビゲーションコントロール： カスタマイズ可能なテンプレートを備えた前へ／次へボタン
• インジケーター： 複数の種類（Default、Dynamic、Fraction、Progress）に対応した、スライド位置を示すマーカー
• アクセシビリティ： キーボードナビゲーションと ARIA 属性に対応し、WCAG 2.2 に完全準拠
• タッチサポート： モバイルデバイスでのスワイプ操作
• 部分表示： アクティブなスライドと並べて隣接するスライドを表示
• 自動再生： 設定可能な間隔でスライドを自動的に切り替え
• テーマ設定： CSS をカスタマイズして表示を完全に制御

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

はじめに

📄 参照： references/getting-started.md

ユーザーが次のことを行う必要がある場合：

• Carousel パッケージをインストールして設定する
• 必要な名前空間を追加し、サービスを登録する
• テーマのスタイルシートとスクリプトを参照する
• アイテムを含む基本的なカルーセルを作成する
• 最初のカルーセル実装をレンダリングする

アイテムの追加と選択

📄 参照： references/populating-items.md

ユーザーが次のことを行う必要がある場合：

• CarouselItem を使ってカルーセルアイテムを追加する
• 初期選択スライドを設定する
• 特定のスライドへプログラムから移動する
• 一部を表示するスライド（隣接するアイテムを表示）を実装する
• 一部表示するスライドのループ動作を設定する
• スライドの選択に SelectedIndex を使用する
• PreviousAsync/NextAsync メソッドを呼び出す

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

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

ユーザーが次のことを行う必要がある場合：

• 前へ／次へナビゲーションボタンの表示／非表示を切り替える
• ホバー時のみナビゲーターを表示する
• ナビゲーターボタンのテンプレートをカスタマイズする
• インジケーターの表示と外観を設定する
• カスタムインジケーターテンプレートを作成する
• インジケーターにスライドのプレビューを表示する
• さまざまなインジケーターの種類（Default、Dynamic、Fraction、Progress）を使用する
• 再生／一時停止ボタンの機能を追加する
• 再生ボタンのテンプレートをカスタマイズする

アクセシビリティ

📄 参照： references/accessibility.md

ユーザーが次のことを行う必要がある場合：

• WCAG 2.2 および Section 508 への準拠を確保する
• カルーセルに適用される WAI-ARIA 属性を理解する
• キーボードナビゲーションを設定する
• キーボードショートカット（矢印キー、Home、End、Space、Enter）を確認する
• キーボード操作を有効または無効にする
• 支援技術に対応する

アニメーションと切り替え

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

ユーザーが次のことを行う必要がある場合：

• 組み込みのアニメーション効果（スライドまたはフェード）を適用する
• CSS でカスタムアニメーションを作成する
• スライドごとに異なる間隔を設定する
• 自動再生を有効または無効にする
• ホバー時の一時停止動作を設定する
• スライドの無限ループを制御する
• スライド変更イベントを処理する
• タッチスワイプを有効または無効にする
• スワイプモード（タッチ、マウス、または両方）を設定する

スタイルと外観

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

次のことが必要な場合：

• CSS クラスの構造を理解する
• インジケーターの外観と間隔をカスタマイズする
• ナビゲーターの位置とスタイルを変更する
• 部分表示スライドのサイズを調整する
• デフォルトのカルーセルスタイルを上書きする
• Theme Studio を使用してカスタムテーマを作成する

クイックスタートの例

画像スライドを使用した、最小限のカルーセル実装例です。

@using Syncfusion.Blazor.Navigations

<SfCarousel>
    <CarouselItem>
        <figure>
            <img src="images/bridge.png" alt="Bridge" style="height:100%;width:100%;" />
            <figcaption>Golden Gate Bridge</figcaption>
        </figure>
    </CarouselItem>
    <CarouselItem>
        <figure>
            <img src="images/trees.png" alt="Trees" style="height:100%;width:100%;" />
            <figcaption>Spring Flower Trees</figcaption>
        </figure>
    </CarouselItem>
    <CarouselItem>
        <figure>
            <img src="images/waterfall.png" alt="Waterfall" style="height:100%;width:100%;" />
            <figcaption>Oddadalen Waterfalls</figcaption>
        </figure>
    </CarouselItem>
</SfCarousel>

前提条件： Syncfusion.Blazor.Navigations パッケージがインストールされており、Syncfusion Blazor サービスが Program.cs に登録されていることを確認してください。セットアップの詳細については、Getting Started を参照してください。

よくあるパターン

パターン 1：ホバー時に一時停止する自動再生カルーセル

<SfCarousel AutoPlay="true" 
            PauseOnHover="true" 
            Interval="3000">
    <CarouselItem>
        <div>Slide 1 Content</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 2 Content</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 3 Content</div>
    </CarouselItem>
</SfCarousel>

使用する場面： 自動切り替えが望ましい一方で、ユーザーがホバーして一時停止できる必要がある、商品紹介やプロモーションバナーに適しています。

パターン 2：ナビゲーターを非表示にし、進行状況インジケーターを表示するカルーセル

<SfCarousel ButtonsVisibility="CarouselButtonVisibility.Hidden"
            IndicatorsType="CarouselIndicatorType.Progress"
            ShowIndicators="true">
    <CarouselItem>
        <div>Slide 1</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 2</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 3</div>
    </CarouselItem>
</SfCarousel>

使用する場面： スライドの位置を示すプログレスバーを備えた、すっきりとしたミニマルなデザインに適しています。タッチスワイプを前提とするモバイルファーストのデザインに向いています。

パターン 3：一部のスライドを表示するプレビュー表示

<SfCarousel PartialVisible="true" 
            Loop="true">
    <CarouselItem>
        <img src="images/image1.png" alt="Image 1" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image2.png" alt="Image 2" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image3.png" alt="Image 3" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image4.png" alt="Image 4" />
    </CarouselItem>
</SfCarousel>

使用する場面： 隣接するスライドを表示することで文脈が伝わり、ナビゲーションを促せる画像ギャラリーに適しています。

パターン 4：ボタンによるプログラムからのナビゲーション

@using Syncfusion.Blazor.Navigations
@using Syncfusion.Blazor.Buttons

<SfCarousel @ref="CarouselRef" 
            ButtonsVisibility="CarouselButtonVisibility.Hidden">
    <CarouselItem><div>Slide 1</div></CarouselItem>
    <CarouselItem><div>Slide 2</div></CarouselItem>
    <CarouselItem><div>Slide 3</div></CarouselItem>
</SfCarousel>

<div class="custom-controls">
    <SfButton @onclick="@(async () => await CarouselRef.PreviousAsync())">Previous</SfButton>
    <SfButton @onclick="@(async () => await CarouselRef.NextAsync())">Next</SfButton>
</div>

@code {
    SfCarousel CarouselRef;
}

使用する場面： カルーセルコンポーネントとは別に、外部のナビゲーションコントロールを備えるカスタム UI デザインに適しています。

パターン 5：カスタム間隔でのフェードアニメーション

<SfCarousel AnimationEffect="CarouselAnimationEffect.Fade">
    <CarouselItem Interval="2000">
        <div>Quick Slide (2s)</div>
    </CarouselItem>
    <CarouselItem Interval="4000">
        <div>Medium Slide (4s)</div>
    </CarouselItem>
    <CarouselItem Interval="6000">
        <div>Long Slide (6s)</div>
    </CarouselItem>
</SfCarousel>

使用する場面： スライドによって必要な閲覧時間が異なる、複雑さにばらつきのあるコンテンツに適しています。

パターン 6：選択インデックスをバインドするカルーセル

<SfCarousel @bind-SelectedIndex="@CurrentSlide">
    <CarouselItem><div>Slide 1</div></CarouselItem>
    <CarouselItem><div>Slide 2</div></CarouselItem>
    <CarouselItem><div>Slide 3</div></CarouselItem>
</SfCarousel>

<p>Current Slide: @CurrentSlide</p>

@code {
    private int CurrentSlide = 0;
}

使用する場面： 現在のスライド位置の追跡、複数のカルーセルの同期、スライドの変更に応じたアクションの実行に適しています。

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

プロパティ	型	デフォルト	説明
AutoPlay	bool	true	スライドの自動切り替えを有効にします
AnimationEffect	CarouselAnimationEffect	Slide	スライド切り替え時のアニメーション（Slide、Fade、Custom、None）
ButtonsVisibility	CarouselButtonVisibility	Visible	ナビゲーターボタンの表示設定（Visible、Hidden、VisibleOnHover）
EnableTouchSwipe	bool	true	タッチデバイスでのスワイプ操作を有効にします
Interval	int	5000	スライド切り替えのデフォルト間隔（ミリ秒）
Loop	bool	true	スライドの無限ループを有効にします
PartialVisible	bool	false	隣接するスライドを一部表示します
PauseOnHover	bool	true	ホバー時に自動再生を一時停止します
SelectedIndex	int	0	現在アクティブなスライドのインデックス
ShowIndicators	bool	true	位置インジケーターの表示／非表示を切り替えます
ShowPlayButton	bool	false	再生／一時停止切り替えボタンを表示します
IndicatorsType	CarouselIndicatorType	Default	インジケーターのスタイル（Default、Dynamic、Fraction、Progress）
SwipeMode	CarouselSwipeMode	Touch & Mouse	スワイプ入力モード
AllowKeyboardInteraction	bool	true	キーボードによるナビゲーションを有効にします

よくあるユースケース

1. Eコマースの商品ギャラリー： ナビゲーション付きで複数の商品画像を表示します
2. ヒーローバナー： ランディングページでプロモーションコンテンツを切り替えます
3. お客様の声スライダー： 顧客レビューを順に表示します
4. ビフォー／アフターの紹介： スライド切り替えによる画像比較を表示します
5. ポートフォリオの表示： プロジェクト画像や事例を紹介します
6. ニュース／記事のハイライト： 注目コンテンツを切り替えて表示します
7. オンボーディングチュートリアル： ステップごとのガイドスライドを表示します
8. 画像ライトボックス： ナビゲーション付きで画像を全画面表示します

次のステップ

• セットアップとインストールについて → はじめにをお読みください
• アイテム管理について → アイテムの追加をお読みください
• UI のカスタマイズについて → ナビゲーターとインジケーターをお読みください
• アクセシビリティへの準拠について → アクセシビリティをお読みください
• アニメーションについて → アニメーションとトランジションをお読みください
• スタイリングについて → スタイルと外観をお読みください