syncfusion-winforms-carousel

Syncfusion WinForms Carousel 控件

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

快速入门

使用自定义控件的基本 Carousel

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);
        }
    }
}

使用图像的基本 Carousel

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);
}

核心概念

Carousel 路径

此控件支持多种路径排列方式：Default（椭圆形）、Orbital（轨道式）、Oval（椭圆形）和 Linear（线性）。每种路径都能为项目提供不同的视觉布局。

图像幻灯片模式

设置 ImageSlides = true 即可专门处理图像。可以通过 ImageListCollection、ImageList 属性或 FilePath 属性添加图像。

自定义控件

任何 WinForms 控件都可以添加到 Carousel 中。控件必须同时添加到 Controls 和 Items 集合中。

透视效果和速度

使用 Perspective 属性控制视觉纵深，使用 TransitionSpeed 属性控制旋转速度。

触控交互

Carousel 可响应触控手势：通过平移／轻扫进行旋转，通过捏合／张开调整透视效果。

导航指南

🚀 开始使用

📄 阅读： references/getting-started.md

• 程序集部署和依赖项
• 通过设计器添加 Carousel
• 通过代码添加 Carousel
• 向 Carousel 添加自定义控件
• 向 Carousel 添加图像
• 初始设置和配置

🛤️ Carousel 路径

📄 阅读： references/carousel-paths.md

• Default（椭圆形）路径
• Orbital（轨道式）路径布局
• Oval（椭圆形）路径布局
• Linear（线性）路径排列
• 为使用场景选择合适的路径
• 路径属性配置

🖼️ 图像幻灯片

📄 阅读： 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：采用自定义颜色的主题 Carousel

// 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	-	用于为背景图像添加阴影的颜色

Carousel 路径选项

路径	描述	使用场景
Default	普通椭圆排列	通用 Carousel、均衡布局
Orbital	轨道曲线排列	太空主题展示、科学类 UI
Oval	椭圆结构排列	宽屏展示、强调水平方向
Linear	水平线性排列	导航条、水平图库

最佳实践

1. 选择合适的路径：根据布局需求选择 Carousel 路径（通用场景使用 Default，水平导航使用 Linear）

2. 添加到两个集合：自定义控件必须同时添加到 Controls 和 Items 集合

3. 为图像启用 ImageSlides：仅处理图像时，将 ImageSlides = true

4. 优化图像数量：保持合理的图像数量（6-12 个项目），以确保流畅运行

5. 设置合适的速度：使用 1.5-3.0 的 TransitionSpeed，便于舒适浏览；快速浏览时可使用更高的值

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：用于定义 Carousel 图像项目的类
• ButtonAdv：常用作 Carousel 项目的增强型按钮
• PictureBox：标准图像控件
• Panel：用于对自定义内容分组的容器控件

故障排除

问题：轮播中未显示项目

• 确保项目同时添加到 Controls 和 Items 集合中
• 确认轮播尺寸足以显示项目
• 检查项目是否设置了适当的尺寸属性

问题：未显示图像

• 确认已设置 ImageSlides = true
• 确认图像路径正确
• 检查图像是否已添加到 ImageListCollection

问题：轮播未旋转

• 如果使用 RotateAlways，请确保将其设为 true
• 检查 TransitionSpeed 是否设为正值
• 确认控件可见且已启用

问题：触摸手势不起作用

• 确保应用面向支持触摸的框架版本
• 在实际触摸设备上测试（不要使用鼠标模拟）
• 检查轮播是否处于焦点状态

问题：项目过多导致性能问题

• 减少项目数量（保持在 6-12 个）
• 添加前压缩大型图像
• 如果旋转卡顿，请降低 TransitionSpeed
• 如果性能至关重要，请考虑禁用 ShowImageShadow