syncfusion-react-carousel

实现 Syncfusion React Carousel 组件

目录

• 概述
• 开始使用
• 填充项目和选择
• 导航和指示器
• 动画和过渡效果
• API 属性
• API 方法
• API 事件
• 样式和外观
• 无障碍功能
• 图像优化
• 常见模式
• 使用场景

Syncfusion React Carousel 组件功能强大且特性齐全，可用于展示图像、内容或任何顺序排列的项目，并支持自动或手动过渡。它支持多种动画效果、可自定义的指示器和导航器、键盘导航，以及全面的无障碍功能。

何时使用此技能

在以下情况下实现 Carousel 组件：

• 创建带平滑过渡效果的轮播图片库
• 构建带导航控件的幻灯片演示
• 为电子商务网站展示产品轮播
• 实现带指示器的用户评价滑块
• 构建支持自动播放功能的内容轮播
• 支持在移动设备上通过触控/滑动进行导航
• 展示符合无障碍标准（WCAG 2.2、Section 508）的项目

组件概述

Carousel 组件负责管理：

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

核心导入：

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

文档与导航指南

开始使用

📄 阅读： references/getting-started.md

• 安装和软件包依赖项
• 使用 Vite 或 Create React App 设置开发环境
• CSS 导入和主题配置（Tailwind、Bootstrap、Fluent、Material）
• 基本 Carousel 组件设置
• 包含项目的首个可运行示例
• 常见设置问题及解决方案

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

填充项目和选择

📄 阅读： references/populating-items.md

• 使用 CarouselItem 指令填充幻灯片
• 使用 itemTemplate 绑定数据源
• 使用 selectedIndex 设置初始幻灯片
• 使用 prev() 和 next() 方法导航
• 显示部分可见的幻灯片（显示相邻幻灯片）
• 以编程方式或声明式方式渲染幻灯片

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

导航器和指示器

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

• 上一页/下一页导航按钮的显示模式
• 自定义导航按钮模板
• 显示/隐藏指示器（进度圆点）
• 四种指示器类型：Default、Dynamic、Fraction、Progress
• 带预览图像的指示器模板
• 播放/暂停按钮控件和模板

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

动画与过渡

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

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

阅读时机： 实现流畅的过渡效果、配置自动播放或添加自定义动画时。

样式与外观

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

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

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

无障碍

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• ARIA 属性与角色
• 键盘交互快捷键（箭头键、Home、End、Space、Enter）
• 屏幕阅读器支持
• 焦点管理与移动设备无障碍

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

图像优化

📄 阅读： references/image-optimization.md

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

阅读时机： 优化轮播性能或使用现代图像格式时。

快速入门示例

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

常见用例

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. 自定义样式的主视觉轮播

• 自定义导航器和指示器样式
• 显示部分幻灯片以提供上下文
• 通过 Theme Studio 自定义
• 参见：styling-and-appearance.md + navigators-and-indicators.md

5. 数据绑定轮播

• 将轮播绑定到 REST API 数据
• 根据项目属性动态生成模板
• 实时更新
• 参见：populating-items.md

完整 API 参考

API 属性参考

📄 阅读： 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 方法参考

📄 阅读： references/api-methods.md

完整介绍所有轮播控制方法：

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

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

API 事件参考

📄 阅读： references/api-events.md

全面介绍事件及完整的事件参数：

• slideChanging - 在过渡开始前触发（可取消）

  • 参数：cancel、currentIndex、currentSlide、nextIndex、nextSlide、isSwiped、name、slideDirection
  • 用例：验证、确认对话框、阻止访问特定幻灯片

• slideChanged - 在过渡结束后触发（不可取消）

  • 参数：currentIndex、currentSlide、previousIndex、previousSlide、isSwiped、name、slideDirection
  • 用例：分析跟踪、更新 UI 计数器、加载内容、触发动画

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

后续步骤

1. 从这里开始： 阅读 getting-started.md 以进行安装和配置
2. 添加内容： 根据 populating-items.md 添加数据
3. 自定义 UI： 使用 navigators-and-indicators.md 配置控件
4. 增强行为： 参考 animations-and-transitions.md 添加效果
5. 打磨设计： 应用 styling-and-appearance.md 中的样式
6. 确保无障碍访问： 按照 accessibility.md 实现合规支持
7. 优化图像： 使用 image-optimization.md 提升性能