syncfusion-winforms-carousel

Syncfusion WinForms Carousel Control

Carousel コントロールは、3D インターフェイスでオブジェクトを表示して回転させる円形コンベヤーです。画像やカスタムコントロールをインタラクティブに操作でき、さまざまなカルーセルパスオプションを使って、視覚的に魅力的な表示を作成できます。

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

次のような場合に Carousel コントロールを使用します。

• インタラクティブな 3D 画像ギャラリーや商品ショーケースを作成する
• カスタムコントロールを備えた回転パネルを表示する
• アイテムや画像の円形ナビゲーションを実装する
• カルーセル効果を使った画像スライドショーを作成する
• 複数の角度から表示できる商品ビューアーを作成する
• タッチ操作に対応した回転インターフェイスを実装する
• アイテムを軌道状または直線状に配置する
• 回転するコンポーネントを使ったビジュアルダッシュボードを構築する
• 3D 効果を使った魅力的な UI プレゼンテーションを作成する

インストール

NuGet でのインストール

Install-Package Syncfusion.Tools.Windows

アセンブリ参照

次のアセンブリへの参照を追加します。

• Syncfusion.Grid.Base
• Syncfusion.Grid.Windows
• Syncfusion.Shared.Base
• Syncfusion.Shared.Windows
• Syncfusion.Tools.Base
• Syncfusion.Tools.Windows

クイックスタート

カスタムコントロールを使用した基本的なカルーセル

using System;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;

namespace CarouselDemo
{
    public partial class Form1 : Form
    {
        private Carousel carousel1;
        
        public Form1()
        {
            InitializeComponent();
            
            // Create Carousel
            carousel1 = new Carousel();
            carousel1.Size = new System.Drawing.Size(600, 400);
            carousel1.Location = new System.Drawing.Point(50, 50);
            
            // Create custom controls (e.g., buttons)
            for (int i = 1; i <= 6; i++)
            {
                ButtonAdv button = new ButtonAdv();
                button.Text = "Item " + i;
                button.Size = new System.Drawing.Size(100, 80);
                button.BackColor = System.Drawing.Color.FromArgb(22, 165, 220);
                button.ForeColor = System.Drawing.Color.White;
                
                // Add to both Controls and Items collections
                carousel1.Controls.Add(button);
                carousel1.Items.Add(button);
            }
            
            // Add to form
            this.Controls.Add(carousel1);
        }
    }
}

画像を使用した基本的なカルーセル

using Syncfusion.Windows.Forms.Tools;

// Enable image slides
carousel1.ImageSlides = true;

// Create and add images
for (int i = 1; i <= 6; i++)
{
    CarouselImage carouselImage = new CarouselImage();
    carouselImage.ItemImage = Image.FromFile($"Images/image{i}.png");
    
    carousel1.ImageListCollection.Add(carouselImage);
}

主なコンセプト

カルーセルパス

このコントロールは、既定（楕円形）、軌道状、楕円形、直線状など、複数のパス配置をサポートしています。各パスでは、アイテムを異なるレイアウトで表示できます。

画像スライドモード

画像を扱うには、ImageSlides = true を有効にします。画像は ImageListCollection、ImageList プロパティ、または FilePath プロパティを使って追加できます。

カスタムコントロール

任意の WinForms コントロールをカルーセルに追加できます。コントロールは Controls コレクションと Items コレクションの両方に追加する必要があります。

パースペクティブと速度

Perspective プロパティで視覚的な奥行きを、TransitionSpeed プロパティで回転速度を調整します。

タッチ操作

カルーセルはタッチジェスチャーに応答します。パンやフリックで回転し、ピンチやストレッチでパースペクティブを調整できます。

ナビゲーションガイド

🚀 はじめに

📄 参照： references/getting-started.md

• アセンブリの配置と依存関係
• デザイナーから Carousel を追加する
• コードから Carousel を追加する
• カルーセルにカスタムコントロールを追加する
• カルーセルに画像を追加する
• 初期設定と構成

🛤️ カルーセルパス

📄 参照： references/carousel-paths.md

• 既定（楕円形）パス
• 軌道状のパスレイアウト
• 楕円形のパスレイアウト
• 直線状のパス配置
• シナリオに適したパスの選び方
• Path プロパティの構成

🖼️ 画像スライド

📄 参照： references/image-slides.md

• ImageSlides モードを有効にする
• ImageListCollection を使って画像を追加する
• ImageList プロパティを使って画像を追加する
• FilePath プロパティを使って画像を追加する
• CarouselImage クラスの使用方法
• 画像管理のベストプラクティス

🎨 ビジュアル構成

📄 参照： references/visual-configuration.md

• Perspective プロパティ（ズーム制御）
• TransitionSpeed プロパティ（回転速度）
• ShowImageShadow プロパティ
• ShowImagePreview プロパティ
• ImageHighlightColor プロパティ
• ImageShadeColor プロパティ
• ビジュアル効果の組み合わせ

🔄 回転動作

📄 参照： references/rotation-behavior.md

• 連続回転の RotateAlways プロパティ
• 自動再生の構成
• プログラムによる回転の制御
• 回転の停止と開始

👆 タッチ操作

📄 参照： references/touch-interactions.md

• タッチサポートの概要
• 回転のためのパンおよびフリックジェスチャー
• パースペクティブ制御のためのピンチおよびストレッチ
• タッチ操作とマウス操作

よくあるパターン

パターン 1：商品画像ギャラリー

// Create image-based carousel for product showcase
Carousel productCarousel = new Carousel();
productCarousel.ImageSlides = true;
productCarousel.CarouselPath = CarouselPath.Default;
productCarousel.Perspective = 4.5f;
productCarousel.TransitionSpeed = 2.0f;
productCarousel.ShowImagePreview = true;
productCarousel.ShowImageShadow = true;

// Add product images
foreach (string imagePath in Directory.GetFiles("Products", "*.jpg"))
{
    CarouselImage img = new CarouselImage();
    img.ItemImage = Image.FromFile(imagePath);
    productCarousel.ImageListCollection.Add(img);
}

this.Controls.Add(productCarousel);

パターン 2：自動回転するダッシュボードパネル

// Create auto-rotating carousel with custom controls
Carousel dashboardCarousel = new Carousel();
dashboardCarousel.CarouselPath = CarouselPath.Orbital;
dashboardCarousel.RotateAlways = true;
dashboardCarousel.TransitionSpeed = 1.5f;
dashboardCarousel.Perspective = 3.0f;

// Add dashboard panels
Panel salesPanel = CreateDashboardPanel("Sales", salesData);
Panel inventoryPanel = CreateDashboardPanel("Inventory", inventoryData);
Panel reportsPanel = CreateDashboardPanel("Reports", reportData);

dashboardCarousel.Controls.Add(salesPanel);
dashboardCarousel.Items.Add(salesPanel);
dashboardCarousel.Controls.Add(inventoryPanel);
dashboardCarousel.Items.Add(inventoryPanel);
dashboardCarousel.Controls.Add(reportsPanel);
dashboardCarousel.Items.Add(reportsPanel);

this.Controls.Add(dashboardCarousel);

パターン 3：直線状のナビゲーションストリップ

// Create linear carousel for horizontal navigation
Carousel navigationCarousel = new Carousel();
navigationCarousel.CarouselPath = CarouselPath.Linear;
navigationCarousel.TransitionSpeed = 3.0f;
navigationCarousel.Size = new Size(800, 150);
navigationCarousel.Dock = DockStyle.Top;

// Add navigation buttons
string[] sections = { "Home", "Products", "Services", "About", "Contact" };
foreach (string section in sections)
{
    ButtonAdv navButton = new ButtonAdv();
    navButton.Text = section;
    navButton.Size = new Size(120, 100);
    navButton.ButtonStyle = ButtonAppearance.Metro;
    
    navigationCarousel.Controls.Add(navButton);
    navigationCarousel.Items.Add(navButton);
}

this.Controls.Add(navigationCarousel);

パターン 4：タッチ操作対応のフォトビューアー

// Create touch-friendly image carousel
Carousel photoViewer = new Carousel();
photoViewer.ImageSlides = true;
photoViewer.CarouselPath = CarouselPath.Oval;
photoViewer.Perspective = 5.0f;
photoViewer.TransitionSpeed = 2.5f;
photoViewer.ShowImagePreview = true;
photoViewer.ImageHighlightColor = Color.Gold;
photoViewer.Dock = DockStyle.Fill;

// Load photos from folder
photoViewer.FilePath = Application.StartupPath + "\\Photos";

this.Controls.Add(photoViewer);
// Touch gestures (pan, flick, pinch, stretch) work automatically

パターン 5：カスタムカラーを使ったテーマ付きカルーセル

// Create visually customized carousel
Carousel themedCarousel = new Carousel();
themedCarousel.ImageSlides = true;
themedCarousel.CarouselPath = CarouselPath.Default;
themedCarousel.BackColor = Color.FromArgb(30, 30, 30);
themedCarousel.Perspective = 4.0f;
themedCarousel.TransitionSpeed = 2.0f;

// Apply custom visual effects
themedCarousel.ShowImageShadow = true;
themedCarousel.ShowImagePreview = true;
themedCarousel.ImageHighlightColor = Color.FromArgb(255, 215, 0); // Gold
themedCarousel.ImageShadeColor = Color.FromArgb(100, 100, 100);   // Gray

// Add images
foreach (var image in imageCollection)
{
    CarouselImage carouselImg = new CarouselImage();
    carouselImg.ItemImage = image;
    themedCarousel.ImageListCollection.Add(carouselImg);
}

this.Controls.Add(themedCarousel);

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

プロパティ	型	既定値	説明
CarouselPath	CarouselPath	Default	パスのレイアウト：Default、Orbital、Oval、Linear
ImageSlides	bool	false	画像専用モードを有効にします
Items	CarouselItemCollection	-	表示する項目のコレクション
ImageListCollection	CarouselImageCollection	-	CarouselImage オブジェクトのコレクション
FilePath	string	""	画像を読み込むフォルダーのパス
Perspective	float	0	楕円表示のズームレベル
TransitionSpeed	float	0	回転速度の倍率
RotateAlways	bool	false	自動回転を継続的に有効にします
ShowImageShadow	bool	false	画像の影を表示します
ShowImagePreview	bool	false	選択した画像のプレビューを中央に表示します
ImageHighlightColor	Color	-	選択した画像を強調表示する色
ImageShadeColor	Color	-	背景画像を暗くする色

カルーセルのパスオプション

パス	説明	用途
Default	標準的な楕円形の配置	一般的なカルーセル、バランスの取れたレイアウト
Orbital	軌道状の曲線配置	宇宙をテーマにした表示、科学的な UI
Oval	楕円形の配置	ワイド画面、横方向を強調する表示
Linear	水平方向の直線配置	ナビゲーションストリップ、横方向のギャラリー

ベストプラクティス

1. 適切なパスを選択する：レイアウトの要件に応じてカルーセルのパスを選択します（一般的な用途には Default、水平方向のナビゲーションには Linear を使用します）

2. 両方のコレクションに追加する：カスタムコントロールは Controls コレクションと Items コレクションの両方に追加する必要があります

3. 画像には ImageSlides を有効にする：画像のみを扱う場合は、ImageSlides = true に設定します

4. 画像の数を最適化する：スムーズなパフォーマンスを保つため、画像の数は適切な範囲（6～12 項目）にします

5. 適切な速度を設定する：快適に閲覧できるよう TransitionSpeed は 1.5～3.0 を使用します。すばやく閲覧する場合は、より高い値を使用します

6. Perspective を適切に設定する：ほとんどのシナリオでは、Perspective の値を 3.0～5.0 にすると効果的です

7. 画像サイズ：パフォーマンスを保つため、画像のサイズが適切であることを確認します（大きな画像は圧縮します）

8. タッチを優先した設計：タッチデバイスを対象とする場合は、タッチ操作向けに設計します。ジェスチャーは自動的に機能します

9. 自動回転をテストする：RotateAlways を使用する場合は、快適に閲覧できる TransitionSpeed が設定されていることを確認します

10. 視覚的なフィードバック：ImageHighlightColor を使用して、選択した項目を明確に示します

フレームワークのサポート

• .NET Framework 4.5 以降
• .NET 6.0、.NET 7.0、.NET 8.0（Windows）
• .NET Core 3.1（Windows）

その他のリソース

• Syncfusion Carousel のドキュメント
• API リファレンス
• ナレッジベースの記事
• GitHub のサンプル

関連コントロール

• CarouselImage：カルーセルの画像項目を定義するクラス
• ButtonAdv：カルーセル項目としてよく使用される拡張ボタン
• PictureBox：標準の画像コントロール
• Panel：カスタムコンテンツをグループ化するコンテナーコントロール

トラブルシューティング

問題：カルーセルに項目が表示されない

• 項目が Controls と Items の両方のコレクションに追加されていることを確認してください
• 項目を表示するのに十分なカルーセルサイズであることを確認してください
• 項目に適切なサイズプロパティが設定されていることを確認してください

問題：画像が表示されない

• ImageSlides = true が設定されていることを確認してください
• 画像のパスが正しいことを確認してください
• 画像が ImageListCollection に追加されていることを確認してください

問題：カルーセルが回転しない

• RotateAlways を使用する場合は、true に設定されていることを確認してください
• TransitionSpeed に正の値が設定されていることを確認してください
• コントロールが表示され、有効になっていることを確認してください

問題：タッチジェスチャーが機能しない

• アプリケーションがタッチ対応のフレームワークバージョンを対象としていることを確認してください
• 実際のタッチデバイスでテストしてください（マウスによるシミュレーションではなく）
• カルーセルにフォーカスがあることを確認してください

問題：項目が多い場合のパフォーマンスの問題

• 項目数を減らしてください（6～12 個に抑えてください）
• 追加する前に大きな画像を圧縮してください
• 回転がぎこちない場合は TransitionSpeed を下げてください
• パフォーマンスが最優先の場合は、ShowImageShadow を無効にすることを検討してください