syncfusion-react-carousel

用途

Syncfusion React Carousel 组件用于在 React 应用中展示图片、内容或任意顺序项，支持自动或手动切换。适合构建轮播图片画廊、幻灯片演示、电商产品轮播、用户评价滑块、带自动播放的内容轮播，以及需要触摸/滑动导航和 WCAG 2.2、Section 508 无障碍合规的场景。

主要能力

组件管理以下方面：

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

核心导入：

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

使用方式

快速开始示例

包含 5 张图片的最小可用轮播：

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;

常见模式

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

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

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

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

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

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

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

<CarouselComponent nextButtonTemplate={nextButtonTemplate} />

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

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

API 属性概览

核心展示属性：

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 属性

API 方法

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

API 事件

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

适用场景

产品画廊（电商）：使用淡入淡出动画显示产品图片，显示指示器，为移动用户启用滑动。
用户评价/评论轮播：以 10 秒间隔自动播放评价，自定义评价模板，悬停暂停以便阅读。
无障碍横幅轮播：使用 Home/End/方向键进行键盘导航，符合 WCAG 2.2 的结构，屏幕阅读器友好的标签。
样式化主视觉轮播：自定义导航器和指示器样式，部分可见幻灯片提供上下文，Theme Studio 自定义。
数据绑定轮播：将轮播绑定到 REST API 数据，基于项属性的动态模板，实时更新。

限制

资料未提供组件的收费、价格、平台限制或具体性能指标等信息。使用前需安装 @syncfusion/ej2-react-navigations 包并配置 CSS 主题。