syncfusion-blazor-carousel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion Blazor Carousel

A comprehensive guide for implementing the Syncfusion Blazor Carousel component - an interactive slideshow for cycling through images, text, or custom content with navigation controls, indicators, and animation effects.

这是一份实现Syncfusion Blazor Carousel组件的综合指南——该组件是一个交互式幻灯片工具，可通过导航控件、指示器和动画效果循环展示图片、文本或自定义内容。

When to Use This Skill

何时使用此技能

Use this skill when the user needs to:

Create image galleries or photo carousels
Build product showcase sliders with multiple items
Implement content rotation with automatic transitions
Add slideshow presentations with navigation controls
Create rotating banners or hero sections
Display testimonials or reviews in a sliding format
Build partial-visible slide layouts (showing previous/next items)
Implement accessible carousels with keyboard navigation
Customize slide transitions with animations
Add play/pause controls for slide automation

当用户需要以下功能时使用此技能：

创建图片画廊或照片轮播
构建包含多个项目的产品展示滑块
实现带自动切换的内容轮播
添加带导航控件的幻灯片展示
创建旋转横幅或首页焦点区域
以滑动格式展示客户评价或反馈
构建半可见幻灯片布局（显示上一张/下一张项目）
实现支持键盘导航的无障碍轮播
自定义带动画的幻灯片过渡效果
添加幻灯片自动播放的暂停/播放控件

Component Overview

组件概述

The Syncfusion Blazor Carousel is a navigation component that allows users to browse through a collection of items in a cyclic manner. It supports:

Multiple Animation Effects: Slide, Fade, or custom CSS animations
Navigation Controls: Previous/Next buttons with customizable templates
Indicators: Visual slide position markers with multiple types (Default, Dynamic, Fraction, Progress)
Accessibility: Full WCAG 2.2 compliance with keyboard navigation and ARIA attributes
Touch Support: Swipe gestures for mobile devices
Partial Views: Show adjacent slides alongside the active slide
Auto Play: Automatic slide transitions with configurable intervals
Theming: CSS customization for complete visual control

Syncfusion Blazor Carousel是一个导航组件，允许用户循环浏览一组项目。它支持：

多种动画效果：滑动、淡入淡出或自定义CSS动画
导航控件：可自定义模板的上一张/下一张按钮
指示器：多种类型的视觉幻灯片位置标记（默认、动态、分数、进度）
无障碍支持：完全符合WCAG 2.2标准，支持键盘导航和ARIA属性
触摸支持：移动设备上的滑动手势
半视图模式：在当前幻灯片旁显示相邻幻灯片
自动播放：可配置间隔的自动幻灯片切换
主题定制：通过CSS实现完全的视觉控制

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

When the user needs to:

Install and configure the Carousel package
Add required namespaces and register services
Reference theme stylesheets and scripts
Create a basic carousel with items
Render initial carousel implementation

📄 阅读： references/getting-started.md

当用户需要：

安装和配置Carousel包
添加所需命名空间并注册服务
引用主题样式表和脚本
创建包含项目的基础轮播
渲染初始轮播实现

Populating Items and Selection

项目填充与选择

📄 Read: references/populating-items.md

When the user needs to:

Add carousel items using CarouselItem
Set the initial selected slide
Navigate programmatically to specific slides
Implement partial visible slides (showing adjacent items)
Configure loop behavior with partial slides
Use SelectedIndex for slide selection
Call PreviousAsync/NextAsync methods

📄 阅读： references/populating-items.md

当用户需要：

使用CarouselItem添加轮播项目
设置初始选中的幻灯片
编程导航到特定幻灯片
实现半可见幻灯片（显示相邻项目）
配置半视图模式下的循环行为
使用SelectedIndex进行幻灯片选择
调用PreviousAsync/NextAsync方法

Navigators and Indicators

导航器与指示器

📄 Read: references/navigators-and-indicators.md

When the user needs to:

Show or hide previous/next navigation buttons
Display navigators only on hover
Customize navigator button templates
Configure indicator visibility and appearance
Create custom indicator templates
Show slide previews in indicators
Use different indicator types (Default, Dynamic, Fraction, Progress)
Add play/pause button functionality
Customize play button template

📄 阅读： references/navigators-and-indicators.md

当用户需要：

显示或隐藏上一张/下一张导航按钮
仅在悬停时显示导航器
自定义导航按钮模板
配置指示器的可见性和外观
创建自定义指示器模板
在指示器中显示幻灯片预览
使用不同的指示器类型（默认、动态、分数、进度）
添加暂停/播放按钮功能
自定义播放按钮模板

Accessibility

无障碍支持

📄 Read: references/accessibility.md

When the user needs to:

Ensure WCAG 2.2 and Section 508 compliance
Understand WAI-ARIA attributes applied to carousel
Configure keyboard navigation
Learn keyboard shortcuts (Arrow keys, Home, End, Space, Enter)
Enable or disable keyboard interaction
Support assistive technologies

📄 阅读： references/accessibility.md

当用户需要：

确保符合WCAG 2.2和Section 508标准
了解应用于轮播的WAI-ARIA属性
配置键盘导航
学习键盘快捷键（方向键、Home、End、空格、回车）
启用或禁用键盘交互
支持辅助技术

Animations and Transitions

动画与过渡

📄 Read: references/animations-and-transitions.md

When the user needs to:

Apply built-in animation effects (Slide or Fade)
Create custom animations with CSS
Set different intervals for each slide
Enable or disable auto play
Configure pause on hover behavior
Control infinite looping of slides
Handle slide change events
Enable or disable touch swipe
Configure swipe modes (Touch, Mouse, or both)

📄 阅读： references/animations-and-transitions.md

当用户需要：

应用内置动画效果（滑动或淡入淡出）
使用CSS创建自定义动画
为每张幻灯片设置不同的切换间隔
启用或禁用自动播放
配置悬停暂停行为
控制幻灯片的无限循环
处理幻灯片切换事件
启用或禁用触摸滑动
配置滑动模式（触摸、鼠标或两者皆可）

Styles and Appearance

样式与外观

📄 Read: references/styles-and-appearance.md

When the user needs to:

Understand CSS class structure
Customize indicator appearance and spacing
Modify navigator position and styling
Adjust partial slide sizing
Override default carousel styles
Use Theme Studio for custom themes

📄 阅读： references/styles-and-appearance.md

当用户需要：

了解CSS类结构
自定义指示器的外观和间距
修改导航器的位置和样式
调整半视图幻灯片的尺寸
覆盖默认轮播样式
使用Theme Studio创建自定义主题

Quick Start Example

快速入门示例

Here's a minimal carousel implementation with image slides:

cshtml

@using Syncfusion.Blazor.Navigations

<SfCarousel>
    <CarouselItem>
        <figure>
            <img src="images/bridge.png" alt="Bridge" style="height:100%;width:100%;" />
            <figcaption>Golden Gate Bridge</figcaption>
        </figure>
    </CarouselItem>
    <CarouselItem>
        <figure>
            <img src="images/trees.png" alt="Trees" style="height:100%;width:100%;" />
            <figcaption>Spring Flower Trees</figcaption>
        </figure>
    </CarouselItem>
    <CarouselItem>
        <figure>
            <img src="images/waterfall.png" alt="Waterfall" style="height:100%;width:100%;" />
            <figcaption>Oddadalen Waterfalls</figcaption>
        </figure>
    </CarouselItem>
</SfCarousel>

Prerequisites: Ensure you have installed

Syncfusion.Blazor.Navigations

package and registered the Syncfusion Blazor service in

Program.cs

. See Getting Started for setup details.

以下是一个包含图片幻灯片的极简轮播实现：

cshtml

@using Syncfusion.Blazor.Navigations

<SfCarousel>
    <CarouselItem>
        <figure>
            <img src="images/bridge.png" alt="Bridge" style="height:100%;width:100%;" />
            <figcaption>Golden Gate Bridge</figcaption>
        </figure>
    </CarouselItem>
    <CarouselItem>
        <figure>
            <img src="images/trees.png" alt="Trees" style="height:100%;width:100%;" />
            <figcaption>Spring Flower Trees</figcaption>
        </figure>
    </CarouselItem>
    <CarouselItem>
        <figure>
            <img src="images/waterfall.png" alt="Waterfall" style="height:100%;width:100%;" />
            <figcaption>Oddadalen Waterfalls</figcaption>
        </figure>
    </CarouselItem>
</SfCarousel>

前提条件： 确保已安装

Syncfusion.Blazor.Navigations

包，并在

Program.cs

中注册Syncfusion Blazor服务。有关设置详情，请参阅快速入门。

Common Patterns

常见模式

Pattern 1: Auto-Playing Carousel with Pause on Hover

模式1：悬停暂停的自动播放轮播

cshtml

<SfCarousel AutoPlay="true" 
            PauseOnHover="true" 
            Interval="3000">
    <CarouselItem>
        <div>Slide 1 Content</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 2 Content</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 3 Content</div>
    </CarouselItem>
</SfCarousel>

When to use: Product showcases, promotional banners where automatic rotation is desired but users need control to pause on hover.

cshtml

<SfCarousel AutoPlay="true" 
            PauseOnHover="true" 
            Interval="3000">
    <CarouselItem>
        <div>Slide 1 Content</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 2 Content</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 3 Content</div>
    </CarouselItem>
</SfCarousel>

适用场景： 产品展示、促销横幅等需要自动轮播，但用户需要在悬停时暂停的场景。

Pattern 2: Carousel with Hidden Navigators and Progress Indicator

模式2：隐藏导航器并带进度指示器的轮播

cshtml

<SfCarousel ButtonsVisibility="CarouselButtonVisibility.Hidden"
            IndicatorsType="CarouselIndicatorType.Progress"
            ShowIndicators="true">
    <CarouselItem>
        <div>Slide 1</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 2</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 3</div>
    </CarouselItem>
</SfCarousel>

When to use: Clean minimal design with progress bar showing slide position, suitable for mobile-first designs relying on touch swipe.

cshtml

<SfCarousel ButtonsVisibility="CarouselButtonVisibility.Hidden"
            IndicatorsType="CarouselIndicatorType.Progress"
            ShowIndicators="true">
    <CarouselItem>
        <div>Slide 1</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 2</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 3</div>
    </CarouselItem>
</SfCarousel>

适用场景： 简洁极简设计，使用进度条显示幻灯片位置，适合依赖触摸滑动的移动端优先设计。

Pattern 3: Partial Visible Slides (Preview Mode)

模式3：半可见幻灯片（预览模式）

cshtml

<SfCarousel PartialVisible="true" 
            Loop="true">
    <CarouselItem>
        <img src="images/image1.png" alt="Image 1" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image2.png" alt="Image 2" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image3.png" alt="Image 3" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image4.png" alt="Image 4" />
    </CarouselItem>
</SfCarousel>

When to use: Image galleries where showing adjacent slides provides context and encourages navigation.

cshtml

<SfCarousel PartialVisible="true" 
            Loop="true">
    <CarouselItem>
        <img src="images/image1.png" alt="Image 1" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image2.png" alt="Image 2" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image3.png" alt="Image 3" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image4.png" alt="Image 4" />
    </CarouselItem>
</SfCarousel>

适用场景： 图片画廊，显示相邻幻灯片可提供上下文并促进导航。

Pattern 4: Programmatic Navigation with Buttons

模式4：带按钮的编程导航

cshtml

@using Syncfusion.Blazor.Navigations
@using Syncfusion.Blazor.Buttons

<SfCarousel @ref="CarouselRef" 
            ButtonsVisibility="CarouselButtonVisibility.Hidden">
    <CarouselItem><div>Slide 1</div></CarouselItem>
    <CarouselItem><div>Slide 2</div></CarouselItem>
    <CarouselItem><div>Slide 3</div></CarouselItem>
</SfCarousel>

<div class="custom-controls">
    <SfButton @onclick="@(async () => await CarouselRef.PreviousAsync())">Previous</SfButton>
    <SfButton @onclick="@(async () => await CarouselRef.NextAsync())">Next</SfButton>
</div>

@code {
    SfCarousel CarouselRef;
}

When to use: Custom UI designs requiring external navigation controls separate from the carousel component.

cshtml

@using Syncfusion.Blazor.Navigations
@using Syncfusion.Blazor.Buttons

<SfCarousel @ref="CarouselRef" 
            ButtonsVisibility="CarouselButtonVisibility.Hidden">
    <CarouselItem><div>Slide 1</div></CarouselItem>
    <CarouselItem><div>Slide 2</div></CarouselItem>
    <CarouselItem><div>Slide 3</div></CarouselItem>
</SfCarousel>

<div class="custom-controls">
    <SfButton @onclick="@(async () => await CarouselRef.PreviousAsync())">Previous</SfButton>
    <SfButton @onclick="@(async () => await CarouselRef.NextAsync())">Next</SfButton>
</div>

@code {
    SfCarousel CarouselRef;
}

适用场景： 自定义UI设计，需要独立于轮播组件的外部导航控件。

Pattern 5: Fade Animation with Custom Intervals

模式5：带自定义间隔的淡入淡出动画

cshtml

<SfCarousel AnimationEffect="CarouselAnimationEffect.Fade">
    <CarouselItem Interval="2000">
        <div>Quick Slide (2s)</div>
    </CarouselItem>
    <CarouselItem Interval="4000">
        <div>Medium Slide (4s)</div>
    </CarouselItem>
    <CarouselItem Interval="6000">
        <div>Long Slide (6s)</div>
    </CarouselItem>
</SfCarousel>

When to use: Content with varying complexity where some slides need more viewing time than others.

cshtml

<SfCarousel AnimationEffect="CarouselAnimationEffect.Fade">
    <CarouselItem Interval="2000">
        <div>Quick Slide (2s)</div>
    </CarouselItem>
    <CarouselItem Interval="4000">
        <div>Medium Slide (4s)</div>
    </CarouselItem>
    <CarouselItem Interval="6000">
        <div>Long Slide (6s)</div>
    </CarouselItem>
</SfCarousel>

适用场景： 内容复杂度不同的场景，部分幻灯片需要更长的展示时间。

Pattern 6: Carousel with Selected Index Binding

模式6：绑定选中索引的轮播

cshtml

<SfCarousel @bind-SelectedIndex="@CurrentSlide">
    <CarouselItem><div>Slide 1</div></CarouselItem>
    <CarouselItem><div>Slide 2</div></CarouselItem>
    <CarouselItem><div>Slide 3</div></CarouselItem>
</SfCarousel>

<p>Current Slide: @CurrentSlide</p>

@code {
    private int CurrentSlide = 0;
}

When to use: Tracking current slide position, synchronizing multiple carousels, or triggering actions based on slide changes.

cshtml

<SfCarousel @bind-SelectedIndex="@CurrentSlide">
    <CarouselItem><div>Slide 1</div></CarouselItem>
    <CarouselItem><div>Slide 2</div></CarouselItem>
    <CarouselItem><div>Slide 3</div></CarouselItem>
</SfCarousel>

<p>Current Slide: @CurrentSlide</p>

@code {
    private int CurrentSlide = 0;
}

适用场景： 跟踪当前幻灯片位置、同步多个轮播，或根据幻灯片切换触发操作。

Key Properties Reference

关键属性参考

Property	Type	Default	Description
`AutoPlay`	bool	true	Enables automatic slide transitions
`AnimationEffect`	CarouselAnimationEffect	Slide	Slide transition animation (Slide, Fade, Custom, None)
`ButtonsVisibility`	CarouselButtonVisibility	Visible	Navigator button visibility (Visible, Hidden, VisibleOnHover)
`EnableTouchSwipe`	bool	true	Enables swipe gestures on touch devices
`Interval`	int	5000	Default time (ms) between slide transitions
`Loop`	bool	true	Enables infinite looping of slides
`PartialVisible`	bool	false	Shows partial view of adjacent slides
`PauseOnHover`	bool	true	Pauses auto play when hovering
`SelectedIndex`	int	0	Index of the currently active slide
`ShowIndicators`	bool	true	Shows/hides position indicators
`ShowPlayButton`	bool	false	Shows play/pause toggle button
`IndicatorsType`	CarouselIndicatorType	Default	Indicator style (Default, Dynamic, Fraction, Progress)
`SwipeMode`	CarouselSwipeMode	Touch & Mouse	Swipe input modes
`AllowKeyboardInteraction`	bool	true	Enables keyboard navigation

属性	类型	默认值	描述
`AutoPlay`	bool	true	启用自动幻灯片切换
`AnimationEffect`	CarouselAnimationEffect	Slide	幻灯片切换动画（滑动、淡入淡出、自定义、无）
`ButtonsVisibility`	CarouselButtonVisibility	Visible	导航按钮可见性（显示、隐藏、悬停时显示）
`EnableTouchSwipe`	bool	true	启用触摸设备上的滑动手势
`Interval`	int	5000	幻灯片切换的默认间隔时间（毫秒）
`Loop`	bool	true	启用幻灯片无限循环
`PartialVisible`	bool	false	显示相邻幻灯片的半视图
`PauseOnHover`	bool	true	悬停时暂停自动播放
`SelectedIndex`	int	0	当前活跃幻灯片的索引
`ShowIndicators`	bool	true	显示/隐藏位置指示器
`ShowPlayButton`	bool	false	显示暂停/播放切换按钮
`IndicatorsType`	CarouselIndicatorType	Default	指示器样式（默认、动态、分数、进度）
`SwipeMode`	CarouselSwipeMode	Touch & Mouse	滑动输入模式
`AllowKeyboardInteraction`	bool	true	启用键盘导航

Common Use Cases

常见使用场景

E-commerce Product Galleries: Display multiple product images with navigation
Hero Banners: Rotating promotional content on landing pages
Testimonial Sliders: Cycling through customer reviews
Before/After Showcases: Image comparisons with slide transitions
Portfolio Displays: Presenting project images or case studies
News/Article Highlights: Featured content rotation
Onboarding Tutorials: Step-by-step guide slides
Image Lightboxes: Full-screen image viewing with navigation

电商产品画廊： 展示多张产品图片并提供导航
首页焦点横幅： 着陆页上的轮换促销内容
评价滑块： 循环展示客户评价
前后对比展示： 带幻灯片过渡的图片对比
作品集展示： 呈现项目图片或案例研究
新闻/文章精选： 精选内容轮播
入门教程： 分步指南幻灯片
图片灯箱： 带导航的全屏图片查看器

Next Steps

下一步

For setup and installation → Read Getting Started
For item management → Read Populating Items
For UI customization → Read Navigators and Indicators
For accessibility compliance → Read Accessibility
For animations → Read Animations and Transitions
For styling → Read Styles and Appearance

如需设置和安装 → 阅读快速入门
如需项目管理 → 阅读项目填充
如需UI定制 → 阅读导航器与指示器
如需无障碍合规 → 阅读无障碍支持
如需动画设置 → 阅读动画与过渡
如需样式定制 → 阅读样式与外观