Back to Details

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

核心属性

PropertyTypePurposeCommon Values
autoPlay
booleanEnable automatic slide transitionstrue, false
interval
numberMilliseconds between auto-transitions5000, 3000
animationEffect
enumTransition animation typeSlide, Fade, None, Custom
buttonsVisibility
enumNavigation button visibilityVisible, Hidden, VisibleOnHover
showIndicators
booleanDisplay slide position indicatorstrue, false
indicatorsType
enumIndicator styleDefault, Dynamic, Fraction, Progress
loop
booleanCycle from last slide to firsttrue, false
pauseOnHover
booleanPause auto-play when hoveringtrue, false
enableTouchSwipe
booleanEnable swipe on touch devicestrue, false
selectedIndex
numberInitial slide index0, 1, 2...
partialVisible
booleanShow adjacent slide previewstrue, 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

下一步操作

  1. Start with Getting Started to set up your environment
  2. Choose your use case from the patterns above
  3. Review the relevant reference section for your features
  4. Check API Reference for complete property documentation
  5. Handle events as needed for your scenario
Need more help? Check individual reference files for detailed examples and advanced configurations.
  1. 从快速入门开始配置开发环境
  2. 从上述模式中选择符合需求的使用场景
  3. 查看对应参考章节获取功能细节
  4. 查阅API参考获取完整属性文档
  5. 根据场景需求处理相关事件
需要更多帮助？ 查看各参考文件获取详细示例与高级配置。