syncfusion-wpf-carousel

カルーセルの実装

Syncfusion WPF Carousel コントロールは、インタラクティブなナビゲーション、データバインディング、カスタムパス、拡大縮小、スキュー、透明度の効果を備えた、アイテムを表示して回転させるための 3D 円形インターフェイスを提供します。標準の円形パスとカスタムの幾何学パスの両方をサポートし、独自のビジュアル体験を実現できます。

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

次のような場合に、このスキルを使用します。

• アイテムを回転する 3D 円形インターフェイスに表示する
• カルーセルナビゲーションを備えた画像ギャラリーを作成する
• 回転する製品ビューアーやポートフォリオを構築する
• キーボードやマウスによるナビゲーションでアイテムを閲覧できるようにする
• アイテム表示用のカスタムパスアニメーションを作成する
• カルーセルアイテムに視覚効果（拡大縮小、透明度、スキュー）を適用する
• データコレクションをインタラクティブな回転形式で表示する
• カスタムパスでページ単位のアイテム表示を実装する
• WPF アプリケーションで視覚的なナビゲーション体験を作成する

コンポーネントの概要

Carousel コントロールには、次の機能があります。

• 標準パスモード：半径を設定できる 3D 円形回転
• カスタムパスモード：アイテムの配置に使用する任意の幾何学パスを定義
• データバインディング：完全なテンプレートサポートでコレクションにバインド
• ナビゲーション：キーボード、マウス、スクロールバー、コマンドによるナビゲーション
• 視覚効果：拡大縮小、透明度、スキュー、回転アニメーション
• アイテム選択：プログラムで制御できる単一選択
• 仮想化：大規模なアイテムコレクションを効率的に読み込み
• カスタマイズ：テンプレートとスタイルを完全にカスタマイズ可能

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

はじめに

📄 参照： references/getting-started.md

• アセンブリのデプロイと NuGet パッケージ
• デザイナー、XAML、または C# から Carousel を追加する方法
• 基本的な構成とセットアップ
• 最初の動作するサンプル
• 必要な名前空間とアセンブリ

アイテムの追加

📄 参照： references/populating-items.md

• CarouselItem を使用したアイテムの追加
• ItemsSource を使用したコレクションへのバインド
• ItemTemplate を使用したアイテムの外観のカスタマイズ
• ItemContainerStyle と StyleSelector の使用
• 大規模なデータセットの仮想化
• アイテムの選択と選択イベント
• フロー方向（RTL サポート）

ナビゲーション機能

📄 参照： references/navigation.md

• キーボードナビゲーション（矢印キー、Home、End、Page Up/Down）
• マウスホイールによるナビゲーション
• スクロールバーによるナビゲーション
• ナビゲーションコマンド（SelectFirstItem、SelectNextItem など）
• プログラムによるナビゲーションメソッド
• カスタムパスモードでのアイテムのループ
• ナビゲーションのパターンとベストプラクティス

標準パスモード

📄 参照： references/standard-path.md

• 3D 円形パス表示（デフォルトモード）
• 半径の設定（RadiusX、RadiusY）
• 回転速度とアニメーション
• アイテムの拡大縮小（ScaleFraction、ScalingEnabled）
• 透明度効果（OpacityFraction、OpacityEnabled）
• アイテムのスキュー（SkewAngleX/Y、有効化プロパティ）
• 標準パスのベストプラクティス

カスタムパスモード

📄 参照： references/custom-path.md

• カスタムの幾何学パスの定義
• ページあたりのアイテム数の設定
• ScaleFraction を使用した全体の拡大縮小
• ScaleFractions を使用した個別アイテムの拡大縮小
• OpacityFraction を使用した全体の透明度
• OpacityFractions を使用した個別アイテムの透明度
• 全体的なスキュー効果
• fractions を使用した個別アイテムのスキュー
• 複雑なパスの例

高度な機能

📄 参照： references/advanced-features.md

• 選択したアイテムを配置する TopItemPosition
• 回転角度の設定
• パスジオメトリのパターンと例
• パフォーマンス最適化の手法
• よくある問題と解決策
• トラブルシューティングガイド

クイックスタートの例

データバインディングを使用した基本的なカルーセル

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Window.DataContext>
        <local:ViewModel/>
    </Window.DataContext>
    
    <syncfusion:Carousel Name="carousel" 
                         Height="400" 
                         Width="600"
                         ItemsSource="{Binding Items}">
        <syncfusion:Carousel.ItemTemplate>
            <DataTemplate>
                <Border Height="100" 
                        Width="150" 
                        BorderBrush="Purple" 
                        BorderThickness="3"
                        Background="LightBlue"
                        CornerRadius="5">
                    <StackPanel HorizontalAlignment="Center" 
                                VerticalAlignment="Center">
                        <Image Source="{Binding ImageSource}" 
                               Height="60" 
                               Width="80"/>
                        <TextBlock Text="{Binding Name}" 
                                   FontWeight="Bold"
                                   Margin="0,5,0,0"/>
                    </StackPanel>
                </Border>
            </DataTemplate>
        </syncfusion:Carousel.ItemTemplate>
    </syncfusion:Carousel>
</Window>

using Syncfusion.Windows.Shared;
using System.Collections.ObjectModel;

// ViewModel
public class ViewModel
{
    public ObservableCollection<CarouselItem> Items { get; set; }
    
    public ViewModel()
    {
        Items = new ObservableCollection<CarouselItem>
        {
            new CarouselItem { Name = "Item 1", ImageSource = "/Images/img1.png" },
            new CarouselItem { Name = "Item 2", ImageSource = "/Images/img2.png" },
            new CarouselItem { Name = "Item 3", ImageSource = "/Images/img3.png" }
        };
    }
}

// Model
public class CarouselItem
{
    public string Name { get; set; }
    public string ImageSource { get; set; }
}

よく使われるパターン

パターン 1：拡大縮小と透明度の効果を備えたカルーセル

<syncfusion:Carousel ItemsSource="{Binding Products}"
                     ScaleFraction="0.7"
                     ScalingEnabled="True"
                     OpacityFraction="0.5"
                     OpacityEnabled="True"
                     RotationSpeed="300">
    <syncfusion:Carousel.ItemTemplate>
        <DataTemplate>
            <Border Height="120" Width="150" 
                    Background="White" 
                    BorderBrush="Gray" 
                    BorderThickness="2">
                <Grid>
                    <Image Source="{Binding ProductImage}" Stretch="Uniform"/>
                    <TextBlock Text="{Binding ProductName}" 
                               VerticalAlignment="Bottom"
                               Background="#CC000000"
                               Foreground="White"
                               Padding="5"/>
                </Grid>
            </Border>
        </DataTemplate>
    </syncfusion:Carousel.ItemTemplate>
</syncfusion:Carousel>

パターン 2：ページング機能を備えたカスタム直線パス

<syncfusion:Carousel VisualMode="CustomPath"
                     ItemsPerPage="5"
                     ItemsSource="{Binding Gallery}"
                     ScaleFraction="0.8"
                     OpacityFraction="0.3">
    <syncfusion:Carousel.Path>
        <Path Data="M0,100 L500,100" 
              Stroke="Blue" 
              StrokeThickness="2"/>
    </syncfusion:Carousel.Path>
    
    <syncfusion:Carousel.ItemTemplate>
        <DataTemplate>
            <Image Source="{Binding}" 
                   Height="100" 
                   Width="100" 
                   Stretch="UniformToFill"/>
        </DataTemplate>
    </syncfusion:Carousel.ItemTemplate>
</syncfusion:Carousel>

パターン 3：プログラムによるナビゲーション

// Navigate to specific items
carousel.SelectFirstItem();
carousel.SelectLastItem();
carousel.SelectNextItem();
carousel.SelectPreviousItem();

// Navigate by pages
carousel.SelectNextPage();
carousel.SelectPreviousPage();

// Set selected item programmatically
carousel.SelectedIndex = 2;

// Using commands in XAML
<Button Content="Next" 
        Command="{Binding ElementName=carousel, Path=SelectNextItemCommand}"/>
<Button Content="Previous" 
        Command="{Binding ElementName=carousel, Path=SelectPreviousItemCommand}"/>

パターン 4：選択項目変更イベント

carousel.SelectionChanged += Carousel_SelectionChanged;

private void Carousel_SelectionChanged(DependencyObject d, 
                                       DependencyPropertyChangedEventArgs e)
{
    var oldItem = e.OldValue;
    var newItem = e.NewValue;
    
    // Get selected item details
    var selectedIndex = carousel.SelectedIndex;
    var selectedItem = carousel.SelectedItem;
    var selectedValue = carousel.SelectedValue;
    
    // Perform actions based on selection
    Debug.WriteLine($"Selected: {selectedItem}");
}

パターン 5：項目ごとの効果を設定したカスタムパス

<syncfusion:Carousel VisualMode="CustomPath"
                     ScalingEnabled="True"
                     OpacityEnabled="True"
                     ItemsSource="{Binding Items}">
    <syncfusion:Carousel.Path>
        <Path Data="M0,0 Q250,200 500,0" 
              Stroke="Red" 
              StrokeThickness="1"/>
    </syncfusion:Carousel.Path>
    
    
    <syncfusion:Carousel.ScaleFractions>
        <syncfusion:PathFractionCollection>
            <syncfusion:FractionValue Fraction="0" Value="0.5"/>
            <syncfusion:FractionValue Fraction="0.5" Value="1.0"/>
            <syncfusion:FractionValue Fraction="1" Value="0.5"/>
        </syncfusion:PathFractionCollection>
    </syncfusion:Carousel.ScaleFractions>
    
    
    <syncfusion:Carousel.OpacityFractions>
        <syncfusion:PathFractionCollection>
            <syncfusion:FractionValue Fraction="0" Value="0.3"/>
            <syncfusion:FractionValue Fraction="0.5" Value="1.0"/>
            <syncfusion:FractionValue Fraction="1" Value="0.3"/>
        </syncfusion:PathFractionCollection>
    </syncfusion:Carousel.OpacityFractions>
</syncfusion:Carousel>

主なプロパティ

プロパティ	説明	デフォルト
VisualMode	表示モード：Standard（円形）または CustomPath	Standard
ItemsSource	カルーセル項目をバインドするコレクション	null
SelectedIndex	選択された項目のインデックス	-1
SelectedItem	現在選択されている項目オブジェクト	null
RadiusX	水平方向の半径（Standard モード）	250
RadiusY	垂直方向の半径（Standard モード）	150
RotationSpeed	アニメーション速度（ミリ秒）	200
ScaleFraction	選択されていない項目の拡大率（0-1）	0
ScalingEnabled	拡大効果の有効／無効	true
OpacityFraction	選択されていない項目の不透明度（0-1）	0
OpacityEnabled	不透明度効果の有効／無効	true
ItemsPerPage	1 ページあたりの表示項目数（CustomPath のみ）	-1（すべて）
EnableLooping	CustomPath モードで項目をループ表示	false
EnableVirtualization	パフォーマンス向上のための UI 仮想化を有効化	false
Path	CustomPath モード用のカスタムパスジオメトリ	null

一般的なユースケース

1. 画像ギャラリービューアー：サムネイル付きの回転カルーセルで写真を表示
2. 製品紹介：3D 回転による E コマース製品の閲覧
3. メディアプレーヤー：アルバムアートや動画サムネイルのカルーセル
4. ダッシュボードナビゲーション：さまざまなダッシュボードビューを移動
5. ポートフォリオ表示：芸術的なレイアウトで作品サンプルを紹介
6. ドキュメントビューアー：ドキュメントのページやプレビューを閲覧
7. チームメンバーギャラリー：経歴情報とともにチームの写真を表示
8. 設定パネル：設定オプションを切り替えて表示
9. チュートリアルの手順：ステップごとの手順を移動
10. タイムライン表示：時系列のイベントを円形形式で表示