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 单独设置项目不透明度
• 全局倾斜效果
• 使用分数值单独倾斜项目
• 复杂路径示例

高级功能

📄 阅读： 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	每页可见项目数（仅适用于 CustomPath）	-1（全部）
EnableLooping	在 CustomPath 模式下循环显示项目	false
EnableVirtualization	启用 UI 虚拟化以提升性能	false
Path	CustomPath 模式的自定义路径几何	null

常见用例

1. 图片库查看器：在旋转轮播中展示照片及缩略图
2. 产品展示：通过 3D 旋转浏览电商产品
3. 媒体播放器：轮播展示专辑封面或视频缩略图
4. 仪表板导航：浏览不同的仪表板视图
5. 作品集展示：以富有艺术感的布局展示作品样本
6. 文档查看器：浏览文档页面或预览
7. 团队成员图库：展示团队照片及个人简介
8. 设置面板：轮播浏览配置选项
9. 教程步骤：按步骤浏览说明
10. 时间线展示：以环形格式展示按时间顺序排列的事件