syncfusion-javascript-carousel

实现 Syncfusion Carousel

Carousel 组件允许用户以幻灯片形式展示带有内容、链接和其他媒体的图像。它非常适合创建图像库、展示轮播内容、精选项目和交互式媒体演示。

主要功能

• 多项渲染 - 显示数组或数据源中的项目
• 动画效果 - 使用 Slide、Fade 或自定义动画实现平滑过渡
• 导航控件 - 提供可配置显示模式的“上一项/下一项”按钮
• 指示器 - 使用数字、圆点、动态或进度指示器显示幻灯片位置
• 自动播放 - 按可配置的时间间隔自动切换幻灯片
• 键盘支持 - 完整支持键盘导航
• 无障碍访问 - 符合 WAI-ARIA 标准，支持辅助技术
• 触控/鼠标滑动 - 在触控设备上通过手势导航
• 模板支持 - 为项目和按钮提供自定义 HTML 模板
• 响应式 - 适配不同屏幕尺寸和部分可见模式

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和依赖项
• 使用 npm 设置软件包
• CSS 导入和主题配置
• Carousel 基本初始化
• 首个可运行示例，包含 HTML 和 TypeScript

填充 Carousel 项目

📄 阅读： references/populating-items.md

• 创建并填充项目数组
• 单个项目的模板语法
• 数据源绑定方法
• 动态项目渲染
• 项目专属配置
• 使用 WebP 图像格式优化性能

动画与过渡

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

• 动画效果类型（Slide、Fade、None、Custom）
• 配置动画时间
• 按需禁用动画
• 动画示例和模式
• 性能注意事项

导航器和指示器

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

• 导航按钮显示模式（Hidden、Visible、VisibleOnHover）
• 指示器类型（Default、Dynamic、Fraction、Progress）
• 自动播放和时间间隔配置
• 播放/暂停按钮控制
• 手动导航幻灯片
• 循环和方向配置

样式与外观

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

• CSS 类结构和自定义
• 设置指示器样式及其外观
• 自定义导航按钮
• 集成 Theme Studio
• 创建自定义主题
• 响应式设计模式

API 参考

📄 阅读： references/api-reference.md

• 完整的属性参考，包含类型和默认值
• 用于 Carousel 控制和导航的 12 个方法
• 事件处理（slideChanged、slideChanging）
• 类型定义和枚举
• 项目模型和数据结构

快速入门示例

import { Carousel } from "@syncfusion/ej2-navigations";

// Create carousel with basic items
const carouselObj = new Carousel({
  items: [
    { template: '<img src="image1.jpg" alt="Image 1" style="height:100%;width:100%;" />' },
    { template: '<img src="image2.jpg" alt="Image 2" style="height:100%;width:100%;" />' },
    { template: '<img src="image3.jpg" alt="Image 3" style="height:100%;width:100%;" />' }
  ],
  animationEffect: "Slide",
  autoPlay: true,
  interval: 3000,
  buttonsVisibility: "Visible"
});

// Append to DOM
carouselObj.appendTo("#carousel");

常见模式

带自动播放的图像库

const carousel = new Carousel({
  items: galleryImages,
  autoPlay: true,
  interval: 4000,
  pauseOnHover: true,
  animationEffect: "Fade"
});
carousel.appendTo("#gallery");

仅手动导航

const carousel = new Carousel({
  items: slides,
  autoPlay: false,
  buttonsVisibility: "Visible",
  indicatorsType: "Numeric"
});
carousel.appendTo("#slides");

带事件处理

const carousel = new Carousel({
  items: items,
  autoPlay: true
});

carousel.addEventListener('slideChanged', (args) => {
  console.log(`Slide changed to: ${args.currentIndex}`);
});

carousel.addEventListener('slideChanging', (args) => {
  if (args.nextIndex === 5) {
    args.cancel = true; // Prevent navigation to slide 5
  }
});

carousel.appendTo("#carousel");

响应式部分可见

const carousel = new Carousel({
  items: items,
  partialVisible: true,
  width: "100%",
  height: "auto",
  animationEffect: "Slide"
});
carousel.appendTo("#container");

关键属性

属性	类型	用途
items	CarouselItemModel[]	要显示的轮播项数组
autoPlay	boolean	启用自动切换幻灯片
interval	number	自动播放切换之间的间隔（毫秒）
animationEffect	CarouselAnimationEffect	幻灯片切换动画类型
buttonsVisibility	CarouselButtonVisibility	显示/隐藏导航按钮
indicatorsType	CarouselIndicatorsType	位置指示器样式
showIndicators	boolean	显示指示圆点/数字
showPlayButton	boolean	显示播放/暂停按钮
pauseOnHover	boolean	悬停时暂停自动播放
enableTouchSwipe	boolean	允许触摸滑动手势
allowKeyboardInteraction	boolean	启用键盘导航
loop	boolean	最后一张幻灯片后从头开始
partialVisible	boolean	部分显示前一张/后一张幻灯片
height	string | number	轮播高度，单位为像素或百分比
width	string | number	轮播宽度，单位为像素或百分比

常见用例

图片库

• 带缩略图的相册
• 展示多张图片的产品展示
• 特色项目轮播

新闻/内容轮播

• 轮播显示标题
• 特色文章轮播
• 用户评价轮播

媒体演示

• 幻灯片查看器
• 作品集演示
• 视频缩略图轮播

电子商务

• 产品图片库
• 特色产品区域
• 分类展示

落地页

• 主视觉图片轮播
• 特色区域轮播
• 促销横幅

---

后续步骤

1. 从入门指南开始 - 设置你的第一个轮播
2. 选择实现方式 - 使用项目数组或绑定数据源
3. 配置动画 - 选择切换效果
4. 添加导航 - 设置按钮和指示器
5. 自定义样式 - 应用你的主题和 CSS
6. 处理事件 - 响应幻灯片变化
7. 查阅 API 参考 - 使用方法进行程序化控制

如需了解详细的实现模式和高级功能，请参阅上方相应的参考指南。