syncfusion-aspnetcore-carousel

实现 Syncfusion ASP.NET Core Carousel 组件

Carousel 组件可显示一组幻灯片，并支持自动切换、触控／鼠标滑动、自定义动画以及多种指示器样式。它非常适合用于图片库、内容轮播、用户评价，以及任何需要按顺序展示内容的场景。

何时使用此技能

在以下情况下使用此技能：

• 创建图片轮播或图库 – 显示多张图片或多个内容项，供用户浏览
• 实现自动幻灯片切换 – 以可配置的间隔和动画展示轮播内容
• 添加导航控件 – 使用上一页／下一页按钮和交互式指示器实现手动导航
• 处理幻灯片切换事件 – 跟踪幻灯片切换，并通过自定义逻辑作出响应
• 支持触控和鼠标交互 – 在移动设备上启用滑动手势，在桌面设备上启用鼠标拖动
• 自定义动画效果 – 在切换过程中应用淡入淡出、滑动或自定义 CSS 动画
• 优化性能 – 使用现代 WebP 格式加载图片，并管理轮播状态持久化
• 构建无障碍幻灯片放映 – 实现键盘导航和适当的 ARIA 支持

组件概述

Carousel 组件由以下部分组成：

• Carousel 容器（<ejs-carousel>）– 主组件包装器
• Carousel 项（<e-carousel-item>）– 各个幻灯片元素
• 导航按钮 – 上一页／下一页控件，支持自定义模板
• 指示器 – 显示当前位置的可视指示器（圆点、动态、分数或进度）
• 播放／暂停控件 – 可选的播放控制界面
• 事件系统 – 用于自定义逻辑的幻灯片切换前和切换后事件

核心概念

• 自动播放 – 按指定间隔自动切换幻灯片
• 循环播放 – 支持从最后一张幻灯片连续循环回到第一张
• 动画效果 – 内置 Slide 和 Fade 效果，以及自定义 CSS 动画
• 部分显示相邻幻灯片 – 在当前幻灯片旁显示相邻幻灯片的预览
• 滑动模式 – 分别控制触控和鼠标滑动交互
• 项模板 – 为每个项设置单独模板，或为所有项设置通用模板
• 数据绑定 – 从数据源或声明式项标记填充轮播内容

文档和导航指南

入门指南

📄 阅读： references/getting-started.md

• 安装 NuGet 包（Syncfusion.EJ2.AspNet.Core）
• 在 _ViewImports.cshtml 中注册 Tag Helper
• 添加样式表和脚本资源（CDN 或本地）
• 使用模板项创建第一个基础轮播
• 验证渲染效果和初始设置

填充项和数据绑定

📄 阅读： references/populating-items.md

• 使用 Carousel 项标记（<e-carousel-item>）填充项
• 使用数据源绑定和 itemTemplate 填充项
• 设置 selectedIndex，从指定幻灯片开始
• 显示部分相邻幻灯片及其预览
• 自定义每项模板或间隔时长

动画和切换效果

📄 阅读： references/animations-transitions.md

• 配置动画效果（None、Slide、Fade、Custom）
• 设置幻灯片切换间隔（毫秒）
• 启用／禁用自动播放和悬停时暂停行为
• 控制幻灯片结束时的循环播放行为
• 禁用触控滑动并配置滑动模式
• 处理幻灯片切换前和切换后事件

导航控件和指示器

📄 阅读： references/navigation-indicators.md

• 显示／隐藏导航按钮（Hidden、Visible、VisibleOnHover）
• 自定义导航按钮模板
• 配置指示器类型（Default、Dynamic、Fraction、Progress）
• 自定义指示器模板和预览
• 启用／禁用播放／暂停按钮控件
• 自定义播放按钮模板

性能与优化

📄 阅读： references/optimization.md

• 使用 WebP 格式加载图片，以提升性能
• 启用页面重新加载后的状态持久化
• 为从右向左书写的语言配置 RTL 渲染
• 自定义 CSS 类
• 优化大型数据集的数据源绑定

API 参考

📄 阅读： references/api-reference.md

• 完整的属性参考，包含说明和类型
• 事件参数和事件处理模式
• 枚举类型和允许的值
• TagHelper 属性映射
• 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>

常见实现模式

模式 1：自动播放图片库

创建自动循环播放幻灯片、并在用户悬停时暂停的图片轮播：

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

模式 2：手动导航与自定义指示器

创建带有手动导航和自定义指示器样式的轮播：

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

模式 3：数据绑定轮播

使用统一模板从数据源填充轮播：

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

模式 4：事件驱动的幻灯片跟踪

处理幻灯片切换并跟踪用户交互：

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

主要属性

属性	类型	用途	常见值
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

常见用例

• 电子商务产品展示 – 展示产品图片并提供导航
• 博客或作品集图片库 – 按顺序展示项目或文章
• 客户评价轮播 – 自动轮换展示客户评价
• 广告／促销内容 – 循环播放促销横幅
• 主视觉区域 – 在着陆页上全宽轮播内容
• 新闻／更新动态 – 通过轮播显示最新新闻
• 社交媒体动态 – 以轮播形式展示图片帖子

浏览器支持

Carousel 组件可在所有现代浏览器中使用：

• Chrome/Edge（最新版）
• Firefox（最新版）
• Safari（最新版）
• 移动浏览器（iOS Safari、Chrome Android）

性能提示

• 使用 WebP 图片以提升性能
• 设置合适的 interval 值以降低 CPU 使用率
• 如不需要，请禁用自动播放
• 使用 partialVisible: false 以减少渲染开销
• 对大型图片库考虑采用图片延迟加载

后续步骤

1. 从入门指南开始设置环境
2. 从上述模式中选择适合你的用例
3. 查看相关参考章节，了解所需功能
4. 查看 API 参考，了解完整的属性文档
5. 根据需要处理事件

---

需要更多帮助？ 请查看各个参考文件，了解详细示例和高级配置。