syncfusion-aspnetcore-carousel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion ASP.NET Core Carousel Component

实现Syncfusion ASP.NET Core Carousel组件

The Carousel component displays a set of slides with support for automatic transitions, touch/mouse swiping, customizable animations, and various indicator styles. It's ideal for image galleries, content rotators, testimonials, and any scenario requiring sequential content presentation.

Carousel组件可展示一组幻灯片，支持自动切换、触摸/鼠标滑动、自定义动画以及多种指示器样式。它非常适合图片画廊、内容轮播、客户评价展示，以及任何需要按顺序呈现内容的场景。

When to Use This Skill

何时使用此技能

Use this skill when you need to:

Create an image carousel or gallery – Display multiple images or content items that users can browse
Implement automatic slide transitions – Show rotating content with configurable intervals and animations
Add navigation controls – Enable manual navigation with previous/next buttons and interactive indicators
Handle slide change events – Track when slides change and respond with custom logic
Support touch and mouse interactions – Enable swipe gestures on mobile and mouse drag on desktop
Customize animation effects – Apply fade, slide, or custom CSS animations during transitions
Optimize performance – Load images in modern WebP format and manage carousel state persistence
Build accessible slideshows – Implement keyboard navigation and proper ARIA support

当你需要以下功能时，可使用此技能：

创建图片轮播或画廊 – 展示多张图片或内容项供用户浏览
实现自动幻灯片切换 – 以可配置的间隔和动画展示轮播内容
添加导航控件 – 通过上一张/下一张按钮和交互式指示器启用手动导航
处理幻灯片切换事件 – 跟踪幻灯片切换时机并通过自定义逻辑做出响应
支持触摸和鼠标交互 – 在移动端启用滑动手势，在桌面端启用鼠标拖拽
自定义动画效果 – 在切换过程中应用淡入淡出、滑动或自定义CSS动画
优化性能 – 以现代WebP格式加载图片并管理轮播状态持久化
构建可访问的幻灯片展示 – 实现键盘导航和适当的ARIA支持

Component Overview

组件概述

The Carousel component consists of:

Carousel container (
```
<ejs-carousel>
```
) – Main component wrapper
Carousel items (
```
<e-carousel-item>
```
) – Individual slide elements
Navigation buttons – Previous/next controls with customizable templates
Indicators – Visual indicators showing current position (dots, dynamic, fraction, or progress)
Play/Pause controls – Optional playback control UI
Event system – Slide changing and slide changed events for custom logic

Carousel组件包含：

轮播容器 (
```
<ejs-carousel>
```
) – 组件主包装器
轮播项 (
```
<e-carousel-item>
```
) – 单个幻灯片元素
导航按钮 – 支持自定义模板的上一张/下一张控件
指示器 – 显示当前位置的视觉指示器（点状、动态、分数或进度条样式）
播放/暂停控件 – 可选的播放控制UI
事件系统 – 用于自定义逻辑的幻灯片切换中（slide changing）和切换完成（slide changed）事件

Key Concepts

核心概念

Auto-play – Automatically transitions between slides at specified intervals
Looping – Allows continuous cycling from last slide back to first
Animation effects – Built-in Slide and Fade effects, plus custom CSS animations
Partial visible slides – Shows adjacent slide previews alongside the active slide
Swipe modes – Independent control of touch and mouse swiping interactions
Item templates – Individual templates per item or a common template for all items
Data binding – Populate carousel from data source or declarative item markup

自动播放 – 按指定间隔自动切换幻灯片
循环播放 – 允许从最后一张幻灯片无缝循环回到第一张
动画效果 – 内置滑动（Slide）和淡入淡出（Fade）效果，支持自定义CSS动画
部分可见幻灯片 – 在当前幻灯片旁显示相邻幻灯片的预览
滑动模式 – 独立控制触摸和鼠标滑动交互
项模板 – 可为每个项设置单独模板，或为所有项使用通用模板
数据绑定 – 通过数据源或声明式项标记填充轮播内容

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Install NuGet packages (Syncfusion.EJ2.AspNet.Core)
Register Tag Helper in
```
_ViewImports.cshtml
```
Add stylesheet and script resources (CDN or local)
Create your first basic carousel with template items
Verify rendering and initial setup

📄 阅读： references/getting-started.md

安装NuGet包（Syncfusion.EJ2.AspNet.Core）
在
```
_ViewImports.cshtml
```
中注册Tag Helper
添加样式表和脚本资源（CDN或本地）
使用模板项创建首个基础轮播
验证渲染效果与初始配置

Populating Items and Data Binding

填充项与数据绑定

📄 Read: references/populating-items.md

Populate items using carousel item markup (
```
<e-carousel-item>
```
)
Populate items using data source binding with
```
itemTemplate
```
Set
```
selectedIndex
```
to start at a specific slide
Show partial visible slides with adjacent slide previews
Customize per-item template or interval duration

📄 阅读： references/populating-items.md

使用轮播项标记（
```
<e-carousel-item>
```
）填充内容
通过
```
itemTemplate
```
绑定数据源来填充项
设置
```
selectedIndex
```
指定起始幻灯片
显示带相邻预览的部分可见幻灯片
自定义单项模板或切换间隔时长

Animations and Transitions

动画与切换效果

📄 Read: references/animations-transitions.md

Configure animation effects (None, Slide, Fade, Custom)
Set slide transition intervals (milliseconds)
Enable/disable auto-play and pause-on-hover behavior
Control looping behavior at the end of slides
Disable touch swipe and configure swipe modes
Handle slide changing and slide changed events

📄 阅读： references/animations-transitions.md

配置动画效果（无、滑动、淡入淡出、自定义）
设置幻灯片切换间隔（毫秒）
启用/禁用自动播放及悬停暂停功能
控制幻灯片末尾的循环行为
禁用触摸滑动并配置滑动模式
处理幻灯片切换中与切换完成事件

Navigation Controls and Indicators

导航控件与指示器

📄 Read: references/navigation-indicators.md

Show/hide navigation buttons (Hidden, Visible, VisibleOnHover)
Customize navigation button templates
Configure indicator types (Default, Dynamic, Fraction, Progress)
Customize indicator templates and previews
Enable/disable play/pause button controls
Customize play button template

📄 阅读： references/navigation-indicators.md

显示/隐藏导航按钮（隐藏、可见、悬停时可见）
自定义导航按钮模板
配置指示器类型（默认、动态、分数、进度条）
自定义指示器模板与预览样式
启用/禁用播放/暂停按钮控件
自定义播放按钮模板

Performance and Optimization

性能与优化

📄 Read: references/optimization.md

Load images in WebP format for better performance
Enable state persistence across page reloads
Configure RTL rendering for right-to-left languages
Apply CSS class customization
Optimize data source binding for large datasets

📄 阅读： references/optimization.md

以WebP格式加载图片提升性能
启用页面刷新后的状态持久化
配置RTL渲染以适配从右到左语言
应用CSS类自定义样式
优化大型数据集的数据源绑定

API Reference

API参考

📄 Read: references/api-reference.md

Complete property reference with descriptions and types
Event arguments and event handling patterns
Enumeration types and allowed values
TagHelper attribute mapping
HTML attributes support

📄 阅读： references/api-reference.md

完整的属性参考（含描述与类型）
事件参数与事件处理模式
枚举类型与允许值
TagHelper属性映射
HTML属性支持

Quick Start Example

快速入门示例

html

<div class="carousel-container">
    <ejs-carousel id="basicCarousel" 
                   autoPlay="true" 
                   animationEffect="Slide"
                   buttonsVisibility="Visible"
                   showIndicators="true">
        <e-carousel-items>
            <e-carousel-item template="#slide1"></e-carousel-item>
            <e-carousel-item template="#slide2"></e-carousel-item>
            <e-carousel-item template="#slide3"></e-carousel-item>
        </e-carousel-items>
    </ejs-carousel>
</div>

<script id="slide1" type="text/x-template">
    <img src="/images/slide1.jpg" alt="Slide 1" style="height: 100%; width: 100%;" />
</script>

<script id="slide2" type="text/x-template">
    <img src="/images/slide2.jpg" alt="Slide 2" style="height: 100%; width: 100%;" />
</script>

<script id="slide3" type="text/x-template">
    <img src="/images/slide3.jpg" alt="Slide 3" style="height: 100%; width: 100%;" />
</script>

<style>
.carousel-container {
    max-width: 600px;
    height: 400px;
    margin: 20px auto;
}
</style>

html

<div class="carousel-container">
    <ejs-carousel id="basicCarousel" 
                   autoPlay="true" 
                   animationEffect="Slide"
                   buttonsVisibility="Visible"
                   showIndicators="true">
        <e-carousel-items>
            <e-carousel-item template="#slide1"></e-carousel-item>
            <e-carousel-item template="#slide2"></e-carousel-item>
            <e-carousel-item template="#slide3"></e-carousel-item>
        </e-carousel-items>
    </ejs-carousel>
</div>

<script id="slide1" type="text/x-template">
    <img src="/images/slide1.jpg" alt="Slide 1" style="height: 100%; width: 100%;" />
</script>

<script id="slide2" type="text/x-template">
    <img src="/images/slide2.jpg" alt="Slide 2" style="height: 100%; width: 100%;" />
</script>

<script id="slide3" type="text/x-template">
    <img src="/images/slide3.jpg" alt="Slide 3" style="height: 100%; width: 100%;" />
</script>

<style>
.carousel-container {
    max-width: 600px;
    height: 400px;
    margin: 20px auto;
}
</style>

Common Implementation Patterns

常见实现模式

Pattern 1: Image Gallery with Auto-Play

模式1：带自动播放的图片画廊

Create an automatic image carousel that cycles through slides and pauses on user hover:

html

<ejs-carousel id="photoGallery" 
              autoPlay="true" 
              pauseOnHover="true"
              interval="3000">
    <e-carousel-items>
        <e-carousel-item template="#photo1"></e-carousel-item>
        <e-carousel-item template="#photo2"></e-carousel-item>
    </e-carousel-items>
</ejs-carousel>

创建可自动循环切换、鼠标悬停时暂停的图片轮播：

html

<ejs-carousel id="photoGallery" 
              autoPlay="true" 
              pauseOnHover="true"
              interval="3000">
    <e-carousel-items>
        <e-carousel-item template="#photo1"></e-carousel-item>
        <e-carousel-item template="#photo2"></e-carousel-item>
    </e-carousel-items>
</ejs-carousel>

Pattern 2: Manual Navigation with Custom Indicators

模式2：带自定义指示器的手动导航轮播

Create a carousel with manual navigation and custom indicator styling:

html

<ejs-carousel id="manualCarousel" 
              autoPlay="false"
              buttonsVisibility="Visible"
              showIndicators="true"
              indicatorsType="Fraction">
    <e-carousel-items>
        <e-carousel-item template="#item1"></e-carousel-item>
        <e-carousel-item template="#item2"></e-carousel-item>
    </e-carousel-items>
</ejs-carousel>

创建支持手动导航和自定义指示器样式的轮播：

html

<ejs-carousel id="manualCarousel" 
              autoPlay="false"
              buttonsVisibility="Visible"
              showIndicators="true"
              indicatorsType="Fraction">
    <e-carousel-items>
        <e-carousel-item template="#item1"></e-carousel-item>
        <e-carousel-item template="#item2"></e-carousel-item>
    </e-carousel-items>
</ejs-carousel>

Pattern 3: Data-Bound Carousel

模式3：数据绑定轮播

Populate carousel from a data source with uniform template:

html

<ejs-carousel id="dataCarousel" 
              dataSource="@Model.Slides"
              itemTemplate="#itemTemplate">
</ejs-carousel>

<script id="itemTemplate" type="text/x-template">
    <div class="slide-content">
        <img src="${image}" alt="${title}" style="height: 100%; width: 100%;" />
        <h3>${title}</h3>
    </div>
</script>

通过数据源填充轮播并使用统一模板：

html

<ejs-carousel id="dataCarousel" 
              dataSource="@Model.Slides"
              itemTemplate="#itemTemplate">
</ejs-carousel>

<script id="itemTemplate" type="text/x-template">
    <div class="slide-content">
        <img src="${image}" alt="${title}" style="height: 100%; width: 100%;" />
        <h3>${title}</h3>
    </div>
</script>

Pattern 4: Event-Driven Slide Tracking

模式4：事件驱动的幻灯片跟踪

Handle slide transitions and track user interactions:

html

<ejs-carousel id="trackedCarousel" 
              slideChanging="onSlideChanging"
              slideChanged="onSlideChanged">
    <e-carousel-items>
        <e-carousel-item template="#slide1"></e-carousel-item>
    </e-carousel-items>
</ejs-carousel>

<script>
function onSlideChanging(args) {
    console.log('Moving from slide ' + args.currentIndex + ' to ' + args.nextIndex);
}

function onSlideChanged(args) {
    console.log('Now on slide ' + args.currentIndex);
}
</script>

处理幻灯片切换并跟踪用户交互：

html

<ejs-carousel id="trackedCarousel" 
              slideChanging="onSlideChanging"
              slideChanged="onSlideChanged">
    <e-carousel-items>
        <e-carousel-item template="#slide1"></e-carousel-item>
    </e-carousel-items>
</ejs-carousel>

<script>
function onSlideChanging(args) {
    console.log('Moving from slide ' + args.currentIndex + ' to ' + args.nextIndex);
}

function onSlideChanged(args) {
    console.log('Now on slide ' + args.currentIndex);
}
</script>

Key Properties

核心属性

Property	Type	Purpose	Common Values
`autoPlay`	boolean	Enable automatic slide transitions	true, false
`interval`	number	Milliseconds between auto-transitions	5000, 3000
`animationEffect`	enum	Transition animation type	Slide, Fade, None, Custom
`buttonsVisibility`	enum	Navigation button visibility	Visible, Hidden, VisibleOnHover
`showIndicators`	boolean	Display slide position indicators	true, false
`indicatorsType`	enum	Indicator style	Default, Dynamic, Fraction, Progress
`loop`	boolean	Cycle from last slide to first	true, false
`pauseOnHover`	boolean	Pause auto-play when hovering	true, false
`enableTouchSwipe`	boolean	Enable swipe on touch devices	true, false
`selectedIndex`	number	Initial slide index	0, 1, 2...
`partialVisible`	boolean	Show adjacent slide previews	true, false

属性	类型	用途	常见值
`autoPlay`	boolean	启用自动幻灯片切换	true, false
`interval`	number	自动切换间隔（毫秒）	5000, 3000
`animationEffect`	enum	切换动画类型	Slide, Fade, None, Custom
`buttonsVisibility`	enum	导航按钮可见性	Visible, Hidden, VisibleOnHover
`showIndicators`	boolean	显示幻灯片位置指示器	true, false
`indicatorsType`	enum	指示器样式	Default, Dynamic, Fraction, Progress
`loop`	boolean	从最后一张幻灯片循环回到第一张	true, false
`pauseOnHover`	boolean	悬停时暂停自动播放	true, false
`enableTouchSwipe`	boolean	启用触摸设备滑动功能	true, false
`selectedIndex`	number	初始幻灯片索引	0, 1, 2...
`partialVisible`	boolean	显示相邻幻灯片预览	true, false

Common Use Cases

常见使用场景

E-Commerce Product Showcase – Display product images with navigation
Blog or Portfolio Gallery – Showcase projects or articles sequentially
Testimonials Carousel – Rotate customer testimonials automatically
Advertisements/Promotions – Cycle promotional banners
Hero Sections – Full-width rotating content on landing pages
News/Updates Feed – Display latest news items in rotating carousel
Social Media Feeds – Show image posts in carousel format

电商产品展示 – 带导航的产品图片轮播
博客或作品集画廊 – 按顺序展示项目或文章
客户评价轮播 – 自动循环展示客户评价
广告/促销横幅 – 循环展示推广横幅
首页Hero区域 – 全屏轮播内容的落地页
新闻/更新信息流 – 轮播展示最新新闻
社交媒体动态 – 以轮播格式展示图片帖子

Browser Support

浏览器支持

The Carousel component works in all modern browsers:

Chrome/Edge (latest)
Firefox (latest)
Safari (latest)
Mobile browsers (iOS Safari, Chrome Android)

Carousel组件支持所有现代浏览器：

Chrome/Edge（最新版）
Firefox（最新版）
Safari（最新版）
移动端浏览器（iOS Safari、Chrome Android）

Performance Tips

性能优化建议

Use WebP images for better performance
Set appropriate
```
interval
```
values to reduce CPU usage
Disable auto-play if not needed
Use
```
partialVisible: false
```
to reduce rendering overhead
Consider lazy-loading images for large galleries

使用WebP格式图片提升性能
设置合适的
```
interval
```
值以降低CPU占用
无需自动播放时禁用该功能
设置
```
partialVisible: false
```
减少渲染开销
大型画廊考虑图片懒加载

Next Steps

下一步操作

Start with Getting Started to set up your environment
Choose your use case from the patterns above
Review the relevant reference section for your features
Check API Reference for complete property documentation
Handle events as needed for your scenario

Need more help? Check individual reference files for detailed examples and advanced configurations.

从快速入门开始配置开发环境
从上述模式中选择符合需求的使用场景
查看对应参考章节获取功能细节
查阅API参考获取完整属性文档
根据场景需求处理相关事件

需要更多帮助？ 查看各参考文件获取详细示例与高级配置。