syncfusion-wpf-carousel
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Carousels
实现轮播控件
The Syncfusion WPF Carousel control provides a 3D circular interface for displaying and rotating through items with interactive navigation, data binding, custom paths, scaling, skewing, and opacity effects. It supports both standard circular paths and custom geometric paths for unique visual experiences.
Syncfusion WPF Carousel控件提供3D环形界面，用于展示内容并支持交互式导航、数据绑定、自定义路径、缩放、倾斜和透明度效果。它同时支持标准环形路径和自定义几何路径，以实现独特的视觉体验。
When to Use This Skill
何时使用该控件
Use this skill when you need to:
- Display items in a rotating circular 3D interface
- Create image galleries with carousel navigation
- Build rotating product viewers or portfolios
- Implement item browsing with keyboard/mouse navigation
- Create custom path animations for item display
- Apply visual effects (scaling, opacity, skewing) to carousel items
- Display data collections in an interactive rotating format
- Implement page-based item display with custom paths
- Create visual navigation experiences in WPF applications
当你需要以下功能时，可使用该控件：
- 在旋转的3D环形界面中展示内容
- 创建带轮播导航的图片画廊
- 构建旋转式产品查看器或作品集
- 实现支持键盘/鼠标导航的内容浏览
- 为内容展示创建自定义路径动画
- 为轮播内容应用视觉效果（缩放、透明度、倾斜）
- 以交互式旋转格式展示数据集合
- 实现基于自定义路径的分页内容展示
- 在WPF应用中创建视觉化导航体验
Component Overview
组件概述
The Carousel control provides:
- Standard Path Mode: Circular 3D rotation with configurable radius
- Custom Path Mode: Define any geometric path for item positioning
- Data Binding: Bind to collections with full template support
- Navigation: Keyboard, mouse, scroll bar, and command-based navigation
- Visual Effects: Scaling, opacity, skewing, and rotation animations
- Item Selection: Single selection with programmatic control
- Virtualization: Efficient loading for large item collections
- Customization: Full template and style customization support
Carousel控件提供以下功能：
- 标准路径模式：可配置半径的3D环形旋转
- 自定义路径模式：定义任意几何路径来定位内容
- 数据绑定：支持绑定集合并提供完整的模板支持
- 导航：键盘、鼠标、滚动条和基于命令的导航
- 视觉效果：缩放、透明度、倾斜和旋转动画
- 内容选择：单选支持，可通过代码控制
- 虚拟化：高效加载大型内容集合
- 自定义化：完整的模板和样式自定义支持
Documentation and Navigation Guide
文档与导航指南
Getting Started
快速入门
📄 Read: references/getting-started.md
- Assembly deployment and NuGet packages
- Adding Carousel via designer, XAML, or C#
- Basic configuration and setup
- First working example
- Required namespaces and assemblies
📄 阅读： references/getting-started.md
- 程序集部署与NuGet包
- 通过设计器、XAML或C#添加Carousel控件
- 基础配置与设置
- 第一个可用示例
- 所需的命名空间与程序集
Populating Items
填充内容
📄 Read: references/populating-items.md
- Adding items using CarouselItem
- Binding to collections with ItemsSource
- Customizing item appearance with ItemTemplate
- Using ItemContainerStyle and StyleSelector
- Virtualization for large datasets
- Item selection and selection events
- Flow direction (RTL support)
📄 阅读： references/populating-items.md
- 使用CarouselItem添加内容
- 通过ItemsSource绑定集合
- 使用ItemTemplate自定义内容外观
- 使用ItemContainerStyle和StyleSelector
- 大型数据集的虚拟化支持
- 内容选择与选择事件
- 流向（RTL支持）
Navigation Features
导航功能
📄 Read: references/navigation.md
- Keyboard navigation (arrow keys, Home, End, Page Up/Down)
- Mouse wheel navigation
- Scroll bar navigation
- Navigation commands (SelectFirstItem, SelectNextItem, etc.)
- Programmatic navigation methods
- Looping items in custom path mode
- Navigation patterns and best practices
📄 阅读： references/navigation.md
- 键盘导航（方向键、Home、End、Page Up/Down）
- 鼠标滚轮导航
- 滚动条导航
- 导航命令（SelectFirstItem、SelectNextItem等）
- 程序化导航方法
- 自定义路径模式下的内容循环
- 导航模式与最佳实践
Standard Path Mode
标准路径模式
📄 Read: references/standard-path.md
- Circular 3D path display (default mode)
- Configuring radius (RadiusX, RadiusY)
- Rotation speed and animation
- Scaling items (ScaleFraction, ScalingEnabled)
- Opacity effects (OpacityFraction, OpacityEnabled)
- Skewing items (SkewAngleX/Y, enabled properties)
- Standard path best practices
📄 阅读： references/standard-path.md
- 3D环形路径展示（默认模式）
- 配置半径（RadiusX、RadiusY）
- 旋转速度与动画
- 内容缩放（ScaleFraction、ScalingEnabled）
- 透明度效果（OpacityFraction、OpacityEnabled）
- 内容倾斜（SkewAngleX/Y、启用属性）
- 标准路径最佳实践
Custom Path Mode
自定义路径模式
📄 Read: references/custom-path.md
- Defining custom geometric paths
- Items per page configuration
- Global scaling with ScaleFraction
- Individual item scaling with ScaleFractions
- Global opacity with OpacityFraction
- Individual item opacity with OpacityFractions
- Global skewing effects
- Individual item skewing with fractions
- Complex path examples
📄 阅读： references/custom-path.md
- 定义自定义几何路径
- 每页内容数量配置
- 全局缩放（ScaleFraction）
- 单个内容缩放（ScaleFractions）
- 全局透明度（OpacityFraction）
- 单个内容透明度（OpacityFractions）
- 全局倾斜效果
- 单个内容倾斜（通过比例值）
- 复杂路径示例
Advanced Features
高级功能
📄 Read: references/advanced-features.md
- TopItemPosition for selected item placement
- Rotation angle configuration
- Path geometry patterns and examples
- Performance optimization techniques
- Common pitfalls and solutions
- Troubleshooting guide
📄 阅读： references/advanced-features.md
- 选中内容的位置（TopItemPosition）
- 旋转角度配置
- 路径几何模式与示例
- 性能优化技巧
- 常见陷阱与解决方案
- 故障排除指南
Quick Start Example
快速入门示例
Basic Carousel with Data Binding
带数据绑定的基础轮播控件
xml
<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>csharp
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; }
}xml
<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>csharp
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; }
}Common Patterns
常见模式
Pattern 1: Carousel with Scaling and Opacity Effects
模式1：带缩放与透明度效果的轮播控件
xml
<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>xml
<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>Pattern 2: Custom Linear Path with Paging
模式2：带分页的自定义线性路径
xml
<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>xml
<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>Pattern 3: Programmatic Navigation
模式3：程序化导航
csharp
// 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}"/>csharp
// 导航到指定内容
carousel.SelectFirstItem();
carousel.SelectLastItem();
carousel.SelectNextItem();
carousel.SelectPreviousItem();
// 按页导航
carousel.SelectNextPage();
carousel.SelectPreviousPage();
// 程序化设置选中内容
carousel.SelectedIndex = 2;
// 在XAML中使用命令
<Button Content="Next"
Command="{Binding ElementName=carousel, Path=SelectNextItemCommand}"/>
<Button Content="Previous"
Command="{Binding ElementName=carousel, Path=SelectPreviousItemCommand}"/>Pattern 4: Selection Changed Event
模式4：选择变更事件
csharp
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}");
}csharp
carousel.SelectionChanged += Carousel_SelectionChanged;
private void Carousel_SelectionChanged(DependencyObject d,
DependencyPropertyChangedEventArgs e)
{
var oldItem = e.OldValue;
var newItem = e.NewValue;
// 获取选中内容详情
var selectedIndex = carousel.SelectedIndex;
var selectedItem = carousel.SelectedItem;
var selectedValue = carousel.SelectedValue;
// 根据选择执行操作
Debug.WriteLine($"Selected: {selectedItem}");
}Pattern 5: Custom Path with Individual Item Effects
模式5：带单个内容效果的自定义路径
xml
<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>
<!-- Individual scaling per position -->
<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>
<!-- Individual opacity per position -->
<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>xml
<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>Key Properties
关键属性
| Property | Description | Default |
|---|---|---|
| Display mode: | |
| Collection to bind carousel items | |
| Index of selected item | |
| Currently selected item object | |
| Horizontal radius (Standard mode) | |
| Vertical radius (Standard mode) | |
| Animation speed in milliseconds | |
| Scale factor for non-selected items (0-1) | |
| Enable/disable scaling effects | |
| Opacity for non-selected items (0-1) | |
| Enable/disable opacity effects | |
| Items visible per page (CustomPath only) | |
| Loop items in CustomPath mode | |
| Enable UI virtualization for performance | |
| Custom path geometry for CustomPath mode | |
| 属性 | 描述 | 默认值 |
|---|---|---|
| 展示模式： | |
| 绑定轮播内容的集合 | |
| 选中内容的索引 | |
| 当前选中的内容对象 | |
| 水平半径（标准模式） | |
| 垂直半径（标准模式） | |
| 动画速度（毫秒） | |
| 非选中内容的缩放比例（0-1） | |
| 启用/禁用缩放效果 | |
| 非选中内容的透明度（0-1） | |
| 启用/禁用透明度效果 | |
| 每页可见内容数量（仅自定义路径模式） | |
| 在自定义路径模式下循环内容 | |
| 启用UI虚拟化以提升性能 | |
| 自定义路径模式下的几何路径 | |
Common Use Cases
常见使用场景
- Image Gallery Viewer: Display photos in rotating carousel with thumbnails
- Product Showcase: E-commerce product browsing with 3D rotation
- Media Player: Album art or video thumbnail carousel
- Dashboard Navigation: Navigate through different dashboard views
- Portfolio Display: Showcase work samples in artistic layouts
- Document Viewer: Browse through document pages or previews
- Team Member Gallery: Display team photos with biographical info
- Settings Panels: Rotate through configuration options
- Tutorial Steps: Navigate through step-by-step instructions
- Timeline Display: Show chronological events in circular format
- 图片画廊查看器：以旋转轮播形式展示照片及缩略图
- 产品展示：电商产品浏览，支持3D旋转
- 媒体播放器：专辑封面或视频缩略图轮播
- 仪表盘导航：在不同仪表盘视图间导航
- 作品集展示：以艺术化布局展示作品样本
- 文档查看器：浏览文档页面或预览内容
- 团队成员画廊：展示团队照片及个人简介
- 设置面板：在配置选项间切换
- 教程步骤：浏览分步指导内容
- 时间线展示：以环形格式展示按时间顺序的事件