syncfusion-react-carousel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing the Syncfusion React Carousel Component

实现Syncfusion React Carousel组件

The Syncfusion React Carousel component is a powerful, fully-featured carousel for displaying images, content, or any sequential items with automatic or manual transitions. It supports multiple animation effects, customizable indicators and navigators, keyboard navigation, and comprehensive accessibility features.

组件概述
快速入门
填充项目与选择
导航与指示器
动画与过渡
API属性
API方法
API事件
样式与外观
无障碍特性
图片优化
常见模式
使用场景

Syncfusion React Carousel组件是一个功能强大、特性完备的轮播组件，可用于展示图片、内容或任何需要自动或手动切换的顺序项。它支持多种动画效果、可自定义的指示器和导航器、键盘导航以及全面的无障碍特性。

When to Use This Skill

何时使用该指南

Implement the Carousel component when you need to:

Create rotating image galleries with smooth transitions
Build slideshow presentations with navigation controls
Display product carousels for e-commerce sites
Implement testimonial sliders with indicators
Build content carousels with auto-play functionality
Support touch/swipe navigation on mobile devices
Display items with accessibility compliance (WCAG 2.2, Section 508)

在以下场景中实现Carousel组件：

创建带有平滑过渡效果的旋转图片画廊
构建带有导航控件的幻灯片演示
为电商网站展示产品轮播
实现带指示器的客户评价滑块
构建带有自动播放功能的内容轮播
支持移动端的触摸/滑动导航
展示符合无障碍标准的内容（WCAG 2.2、Section 508）

Component Overview

组件概述

The Carousel component manages:

Visual Display: Renders one active slide with customizable templates
Navigation: Previous/next buttons with multiple visibility modes
Indicators: Show current position with multiple indicator types (dots, fractions, progress bars)
Animations: Smooth slide transitions with fade, slide, or custom effects
Interaction: Auto-play, manual swipe, keyboard navigation
Accessibility: Full ARIA support, keyboard shortcuts, screen reader compatibility

Core imports:

import { CarouselComponent, CarouselItemsDirective, CarouselItemDirective } from "@syncfusion/ej2-react-navigations";

Carousel组件可管理：

视觉展示： 渲染单个活跃幻灯片，支持自定义模板
导航： 上一张/下一张按钮，支持多种可见性模式
指示器： 通过多种指示器类型（圆点、分数、进度条）显示当前位置
动画： 带有淡入、滑动或自定义效果的平滑幻灯片过渡
交互： 自动播放、手动滑动、键盘导航
无障碍： 完整的ARIA支持、键盘快捷键、屏幕阅读器兼容

核心导入：

import { CarouselComponent, CarouselItemsDirective, CarouselItemDirective } from "@syncfusion/ej2-react-navigations";

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package dependencies
Development environment setup with Vite or Create React App
CSS imports and theme configuration (Tailwind, Bootstrap, Fluent, Material)
Basic carousel component setup
First working example with items
Common setup issues and solutions

When to read: First time setting up Carousel or troubleshooting initial setup problems.

📄 阅读： references/getting-started.md

安装与包依赖
使用Vite或Create React App搭建开发环境
CSS导入与主题配置（Tailwind、Bootstrap、Fluent、Material）
基础轮播组件设置
首个可运行的项目示例
常见设置问题与解决方案

阅读时机： 首次设置Carousel或排查初始配置问题时。

Populating Items and Selection

填充项目与选择

📄 Read: references/populating-items.md

Populating slides using CarouselItem directives
Data source binding with itemTemplate
Setting initial slide with selectedIndex
Navigation with prev() and next() methods
Partial visible slides (showing adjacent slides)
Programmatic vs. declarative slide rendering

When to read: Building slide content, handling dynamic data, or implementing navigation controls.

📄 阅读： references/populating-items.md

使用CarouselItem指令填充幻灯片
通过itemTemplate绑定数据源
使用selectedIndex设置初始幻灯片
使用prev()和next()方法实现导航
部分可见幻灯片（显示相邻幻灯片）
程序化与声明式幻灯片渲染对比

阅读时机： 构建幻灯片内容、处理动态数据或实现导航控件时。

Navigators and Indicators

导航器与指示器

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

Previous/next navigator button visibility modes
Custom navigator button templates
Showing/hiding indicators (progress dots)
Four indicator types: Default, Dynamic, Fraction, Progress
Indicator templates with preview images
Play/pause button control and templates

When to read: Customizing navigation UI, changing indicator style, or implementing play controls.

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

上一张/下一张导航按钮的可见性模式
自定义导航按钮模板
显示/隐藏指示器（进度圆点）
四种指示器类型：默认、动态、分数、进度
带预览图片的指示器模板
播放/暂停按钮的控制与模板

阅读时机： 自定义导航UI、修改指示器样式或实现播放控件时。

Animations and Transitions

动画与过渡

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

Animation effects (Fade, Slide, Custom CSS)
Setting slide transition intervals per item
Auto-play configuration and timing
Pause on hover behavior
Looping and non-looping behavior
Touch swipe modes and disabled interactions
Slide changing events (slideChanging, slideChanged)

When to read: Implementing smooth transitions, configuring auto-play, or adding custom animations.

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

动画效果（淡入、滑动、自定义CSS）
为每个项目设置幻灯片过渡间隔
自动播放配置与计时
悬停暂停行为
循环与非循环行为
触摸滑动模式与禁用交互
幻灯片切换事件（slideChanging、slideChanged）

阅读时机： 实现平滑过渡、配置自动播放或添加自定义动画时。

Styling and Appearance

样式与外观

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

CSS class structure for customization
Customizing indicator appearance and spacing
Navigator button positioning and styling
Partial slide area customization
Theme Studio integration for visual theming
Dark mode and custom color schemes

When to read: Styling indicators/navigators, positioning elements, or creating custom themes.

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

用于自定义的CSS类结构
自定义指示器外观与间距
导航按钮的定位与样式
部分幻灯片区域的自定义
Theme Studio集成实现视觉主题定制
深色模式与自定义配色方案

阅读时机： 设置指示器/导航器样式、定位元素或创建自定义主题时。

Accessibility

无障碍特性

📄 Read: references/accessibility.md

WCAG 2.2 and Section 508 compliance
ARIA attributes and roles
Keyboard interaction shortcuts (arrows, Home, End, Space, Enter)
Screen reader support
Focus management and mobile accessibility

When to read: Building accessible carousels or implementing keyboard navigation.

📄 阅读： references/accessibility.md

符合WCAG 2.2与Section 508标准
ARIA属性与角色
键盘交互快捷键（方向键、Home、End、空格、回车）
屏幕阅读器支持
焦点管理与移动端无障碍

阅读时机： 构建无障碍轮播或实现键盘导航时。

Image Optimization

图片优化

📄 Read: references/image-optimization.md

Loading carousel images in WebP format
Performance benefits and file size reduction
Image format conversion techniques
Implementation with carousel items

When to read: Optimizing carousel performance or implementing modern image formats.

📄 阅读： references/image-optimization.md

以WebP格式加载轮播图片
性能优势与文件大小缩减
图片格式转换技巧
在轮播项目中的实现方式

阅读时机： 优化轮播性能或实现现代图片格式时。

Quick Start Example

快速入门示例

Minimal working carousel with 5 images:

tsx

import { CarouselComponent, CarouselItemsDirective, CarouselItemDirective } from "@syncfusion/ej2-react-navigations";
import * as React from "react";

const App = () => {
  return (
    <div className='control-container'>
      <CarouselComponent>
        <CarouselItemsDirective>
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="cardinal" style="height:100%;width:100%;" /><figcaption class="img-caption">Cardinal</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="kingfisher" style="height:100%;width:100%;" /><figcaption class="img-caption">Kingfisher</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="toucan" style="height:100%;width:100%;" /><figcaption class="img-caption">Toucan</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="warbler" style="height:100%;width:100%;" /><figcaption class="img-caption">Warbler</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="bee-eater" style="height:100%;width:100%;" /><figcaption class="img-caption">Bee-eater</figcaption></figure>' />
        </CarouselItemsDirective>
      </CarouselComponent>
    </div>
  );
}

export default App;

包含5张图片的最简可运行轮播：

tsx

import { CarouselComponent, CarouselItemsDirective, CarouselItemDirective } from "@syncfusion/ej2-react-navigations";
import * as React from "react";

const App = () => {
  return (
    <div className='control-container'>
      <CarouselComponent>
        <CarouselItemsDirective>
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="cardinal" style="height:100%;width:100%;" /><figcaption class="img-caption">Cardinal</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="kingfisher" style="height:100%;width:100%;" /><figcaption class="img-caption">Kingfisher</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="toucan" style="height:100%;width:100%;" /><figcaption class="img-caption">Toucan</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="warbler" style="height:100%;width:100%;" /><figcaption class="img-caption">Warbler</figcaption></figure>' />
          <CarouselItemDirective template='<figure class="img-container"><img src="url" alt="bee-eater" style="height:100%;width:100%;" /><figcaption class="img-caption">Bee-eater</figcaption></figure>' />
        </CarouselItemsDirective>
      </CarouselComponent>
    </div>
  );
}

export default App;

Common Patterns

常见模式

Pattern 1: Auto-Play Gallery with Indicators and Navigators

模式1：带指示器与导航器的自动播放画廊

tsx

<CarouselComponent autoPlay={true} showIndicators={true} buttonsVisibility="Visible">
  <CarouselItemsDirective>
    {/* items */}
  </CarouselItemsDirective>
</CarouselComponent>

tsx

<CarouselComponent autoPlay={true} showIndicators={true} buttonsVisibility="Visible">
  <CarouselItemsDirective>
    {/* 项目 */}
  </CarouselItemsDirective>
</CarouselComponent>

Pattern 2: Data-Driven Carousel with Dynamic Content

模式2：带动态内容的数据驱动轮播

tsx

const itemTemplate = (props: any): JSX.Element => {
  return <img src={props.imageUrl} alt={props.title} />;
}

<CarouselComponent dataSource={carouselData} itemTemplate={itemTemplate} />

tsx

const itemTemplate = (props: any): JSX.Element => {
  return <img src={props.imageUrl} alt={props.title} />;
}

<CarouselComponent dataSource={carouselData} itemTemplate={itemTemplate} />

Pattern 3: Carousel with Custom Navigation Buttons

模式3：带自定义导航按钮的轮播

tsx

const nextButtonTemplate = (props: any): JSX.Element => {
  return <ButtonComponent iconCss="e-icons e-chevron-right" />;
}

<CarouselComponent nextButtonTemplate={nextButtonTemplate} />

tsx

const nextButtonTemplate = (props: any): JSX.Element => {
  return <ButtonComponent iconCss="e-icons e-chevron-right" />;
}

<CarouselComponent nextButtonTemplate={nextButtonTemplate} />

Pattern 4: Touch-Enabled Mobile Carousel

模式4：支持触摸的移动端轮播

tsx

<CarouselComponent 
  enableTouchSwipe={true} 
  swipeMode={CarouselSwipeMode.Touch & CarouselSwipeMode.Mouse}
  pauseOnHover={true}
>
  {/* items */}
</CarouselComponent>

tsx

<CarouselComponent 
  enableTouchSwipe={true} 
  swipeMode={CarouselSwipeMode.Touch & CarouselSwipeMode.Mouse}
  pauseOnHover={true}
>
  {/* 项目 */}
</CarouselComponent>

API Properties Overview

API属性概述

Core Display Properties:

```
dataSource
```
- Bind carousel to external data
```
itemTemplate
```
- Template for data-bound items
```
items
```
- Collection of CarouselItemModel
```
selectedIndex
```
- Current slide index

Animation & Behavior:

```
animationEffect
```
- Animation type (None, Slide, Fade, Custom)
```
interval
```
- Transition delay in milliseconds (default: 5000)
```
autoPlay
```
- Enable auto-play (default: false)
```
loop
```
- Loop slides infinitely (default: true)
```
pauseOnHover
```
- Pause on hover (default: true)
```
enableTouchSwipe
```
- Enable touch swiping (default: true)
```
swipeMode
```
- Touch/mouse swipe modes (Touch, Mouse)

UI Controls:

```
buttonsVisibility
```
- Navigator buttons (Hidden, Visible, VisibleOnHover)
```
showIndicators
```
- Show indicators (default: true)
```
showPlayButton
```
- Show play/pause button (default: false)
```
indicatorsType
```
- Indicator style (Default, Dynamic, Fraction, Progress)

Customization:

```
previousButtonTemplate
```
- Previous button UI
```
nextButtonTemplate
```
- Next button UI
```
playButtonTemplate
```
- Play/pause button UI
```
indicatorsTemplate
```
- Indicators UI
```
cssClass
```
- Custom CSS classes
```
partialVisible
```
- Show adjacent slides (default: false)
```
allowKeyboardInteraction
```
- Keyboard navigation (default: true)

Layout & Localization:

```
height
```
- Component height (pixels/percentage)
```
width
```
- Component width (pixels/percentage)
```
enableRtl
```
- Right-to-left support
```
enablePersistence
```
- Persist state between reloads
```
locale
```
- Culture/localization setting
```
htmlAttributes
```
- Custom HTML attributes

核心展示属性：

```
dataSource
```
- 将轮播绑定到外部数据
```
itemTemplate
```
- 数据绑定项目的模板
```
items
```
- CarouselItemModel集合
```
selectedIndex
```
- 当前幻灯片索引

动画与行为：

```
animationEffect
```
- 动画类型（None、Slide、Fade、Custom）
```
interval
```
- 过渡延迟（毫秒，默认：5000）
```
autoPlay
```
- 启用自动播放（默认：false）
```
loop
```
- 无限循环幻灯片（默认：true）
```
pauseOnHover
```
- 悬停时暂停（默认：true）
```
enableTouchSwipe
```
- 启用触摸滑动（默认：true）
```
swipeMode
```
- 触摸/鼠标滑动模式（Touch、Mouse）

UI控件：

```
buttonsVisibility
```
- 导航按钮（Hidden、Visible、VisibleOnHover）
```
showIndicators
```
- 显示指示器（默认：true）
```
showPlayButton
```
- 显示播放/暂停按钮（默认：false）
```
indicatorsType
```
- 指示器样式（Default、Dynamic、Fraction、Progress）

自定义：

```
previousButtonTemplate
```
- 上一张按钮UI
```
nextButtonTemplate
```
- 下一张按钮UI
```
playButtonTemplate
```
- 播放/暂停按钮UI
```
indicatorsTemplate
```
- 指示器UI
```
cssClass
```
- 自定义CSS类
```
partialVisible
```
- 显示相邻幻灯片（默认：false）
```
allowKeyboardInteraction
```
- 键盘导航（默认：true）

布局与本地化：

```
height
```
- 组件高度（像素/百分比）
```
width
```
- 组件宽度（像素/百分比）
```
enableRtl
```
- 从右到左支持
```
enablePersistence
```
- 重新加载时保留状态
```
locale
```
- 文化/本地化设置
```
htmlAttributes
```
- 自定义HTML属性

Common Use Cases

常见使用场景

1. Product Gallery (E-Commerce)

Display product images with fade animation
Show indicators to indicate available images
Enable swipe for mobile users
See: populating-items.md + animations-and-transitions.md

2. Testimonial/Review Carousel

Auto-play testimonials with 10-second intervals
Custom testimonial template
Pause on hover to allow reading
See: populating-items.md + animations-and-transitions.md

3. Accessible Banner Carousel

Keyboard navigation with Home/End/Arrow keys
WCAG 2.2 compliant structure
Screen reader friendly labels
See: accessibility.md

4. Styled Hero Carousel

Custom navigator and indicator styling
Partial visible slides for context
Theme Studio customization
See: styling-and-appearance.md + navigators-and-indicators.md

5. Data-Bound Carousel

Bind carousel to REST API data
Dynamic templates based on item properties
Real-time updates
See: populating-items.md

1. 产品画廊（电商）

展示带淡入动画的产品图片
显示指示器表明可用图片数量
为移动端用户启用滑动功能
参考：populating-items.md + animations-and-transitions.md

2. 客户评价轮播

自动播放评价，间隔10秒
自定义评价模板
悬停时暂停以便阅读
参考：populating-items.md + animations-and-transitions.md

3. 无障碍横幅轮播

支持Home/End/方向键的键盘导航
符合WCAG 2.2标准的结构
屏幕阅读器友好的标签
参考：accessibility.md

4. 样式化Hero轮播

自定义导航器与指示器样式
部分可见幻灯片提供上下文
Theme Studio定制
参考：styling-and-appearance.md + navigators-and-indicators.md

5. 数据绑定轮播

将轮播绑定到REST API数据
基于项目属性的动态模板
实时更新
参考：populating-items.md

Complete API Reference

完整API参考

API Properties Reference

API属性参考

📄 Read: references/api-properties.md

Comprehensive documentation for all 28+ carousel properties organized by functionality:

Core Data & Selection: dataSource, itemTemplate, items, selectedIndex
Animation & Timing: animationEffect, interval, autoPlay, loop, pauseOnHover
Navigation & Indicators: buttonsVisibility, showIndicators, indicatorsType, showPlayButton
Template & Customization: Button/indicator templates, cssClass, partialVisible
Interaction & Accessibility: enableTouchSwipe, swipeMode, allowKeyboardInteraction
Layout & Localization: height, width, enableRtl, enablePersistence, locale, htmlAttributes

Each property includes type information, default values, and practical code examples.

📄 阅读： references/api-properties.md

按功能分类的28+个轮播属性的全面文档：

核心数据与选择： dataSource、itemTemplate、items、selectedIndex
动画与计时： animationEffect、interval、autoPlay、loop、pauseOnHover
导航与指示器： buttonsVisibility、showIndicators、indicatorsType、showPlayButton
模板与自定义： 按钮/指示器模板、cssClass、partialVisible
交互与无障碍： enableTouchSwipe、swipeMode、allowKeyboardInteraction
布局与本地化： height、width、enableRtl、enablePersistence、locale、htmlAttributes

每个属性包含类型信息、默认值和实用代码示例。

API Methods Reference

API方法参考

📄 Read: references/api-methods.md

Complete documentation for all carousel control methods:

next()
- Navigate to next slide with loop support
prev()
- Navigate to previous slide with loop support
getHostElement()
- Access underlying carousel DOM element

Includes method signatures, use cases, practical examples, and advanced patterns like skip multiple slides, go to specific slide, and scroll-to-carousel functionality.

📄 阅读： references/api-methods.md

所有轮播控制方法的完整文档：

next()
- 导航到下一张幻灯片，支持循环
prev()
- 导航到上一张幻灯片，支持循环
getHostElement()
- 访问底层轮播DOM元素

包含方法签名、使用场景、实用示例以及跳过多张幻灯片、跳转到指定幻灯片、滚动到轮播等高级模式。

API Events Reference

API事件参考

📄 Read: references/api-events.md

Comprehensive event documentation with complete event arguments:

slideChanging
- Fires BEFORE transition (cancelable)
- Arguments: cancel, currentIndex, currentSlide, nextIndex, nextSlide, isSwiped, name, slideDirection
- Use cases: Validation, confirmation dialogs, preventing access to specific slides
slideChanged
- Fires AFTER transition (not cancelable)
- Arguments: currentIndex, currentSlide, previousIndex, previousSlide, isSwiped, name, slideDirection
- Use cases: Analytics tracking, updating UI counters, loading content, triggering animations

Includes practical examples for rate limiting, history tracking, analytics integration, and event pattern library.

📄 阅读： references/api-events.md

包含完整事件参数的全面事件文档：

slideChanging
- 过渡前触发（可取消）
- 参数：cancel、currentIndex、currentSlide、nextIndex、nextSlide、isSwiped、name、slideDirection
- 使用场景：验证、确认对话框、阻止访问特定幻灯片
slideChanged
- 过渡后触发（不可取消）
- 参数：currentIndex、currentSlide、previousIndex、previousSlide、isSwiped、name、slideDirection
- 使用场景：分析跟踪、更新UI计数器、加载内容、触发动画

包含速率限制、历史跟踪、分析集成和事件模式库的实用示例。

Next Steps

下一步

Start here: Read getting-started.md to install and configure
Add content: Follow populating-items.md for your data
Customize UI: Use navigators-and-indicators.md for controls
Enhance behavior: Reference animations-and-transitions.md for effects
Polish design: Apply styling-and-appearance.md for styling
Ensure access: Implement accessibility.md for compliance
Optimize images: Use image-optimization.md for performance

从这里开始： 阅读getting-started.md进行安装和配置
添加内容： 按照populating-items.md处理你的数据
自定义UI： 使用navigators-and-indicators.md配置控件
增强行为： 参考animations-and-transitions.md添加效果
优化设计： 应用styling-and-appearance.md设置样式
确保无障碍： 实现accessibility.md以符合标准
优化图片： 使用image-optimization.md提升性能