syncfusion-blazor-carousel

Syncfusion Blazor Carousel

全面介绍如何实现 Syncfusion Blazor Carousel 组件——这是一款交互式幻灯片组件，可循环展示图片、文本或自定义内容，并提供导航控件、指示器和动画效果。

何时使用此技能

在用户需要以下功能时使用此技能：

• 创建图片库或照片轮播
• 构建包含多个项目的产品展示滑块
• 实现带自动切换效果的内容轮播
• 添加带导航控件的幻灯片演示
• 创建轮播横幅或主视觉区域
• 以滑动形式展示客户评价或评论
• 构建部分可见的幻灯片布局（显示前一项和下一项）
• 实现支持键盘导航的无障碍轮播
• 使用动画自定义幻灯片切换效果
• 添加幻灯片自动播放的播放／暂停控件

组件概述

Syncfusion Blazor Carousel 是一种导航组件，允许用户以循环方式浏览一组项目。它支持：

• 多种动画效果： 滑动、淡入淡出或自定义 CSS 动画
• 导航控件： 上一项／下一项按钮，并支持自定义模板
• 指示器： 可视化的幻灯片位置标记，支持多种类型（Default、Dynamic、Fraction、Progress）
• 无障碍功能： 完全符合 WCAG 2.2 标准，支持键盘导航和 ARIA 属性
• 触控支持： 支持移动设备上的滑动手势
• 部分视图： 显示当前幻灯片旁边的相邻幻灯片
• 自动播放： 按可配置的时间间隔自动切换幻灯片
• 主题设置： 可通过 CSS 自定义，实现全面的视觉控制

文档和导航指南

入门

📄 阅读： references/getting-started.md

在用户需要以下功能时：

• 安装并配置 Carousel 包
• 添加所需的命名空间并注册服务
• 引用主题样式表和脚本
• 创建包含项目的基本轮播
• 渲染初始轮播实现

填充项目和选择

📄 阅读： references/populating-items.md

在用户需要以下功能时：

• 使用 CarouselItem 添加轮播项目
• 设置初始选中的幻灯片
• 以编程方式导航到指定幻灯片
• 实现部分可见的幻灯片（显示相邻项目）
• 配置部分幻灯片的循环行为
• 使用 SelectedIndex 选择幻灯片
• 调用 PreviousAsync/NextAsync 方法

导航器和指示器

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

在用户需要以下功能时：

• 显示或隐藏上一项／下一项导航按钮
• 仅在悬停时显示导航器
• 自定义导航按钮模板
• 配置指示器的可见性和外观
• 创建自定义指示器模板
• 在指示器中显示幻灯片预览
• 使用不同的指示器类型（Default、Dynamic、Fraction、Progress）
• 添加播放／暂停按钮功能
• 自定义播放按钮模板

无障碍功能

📄 阅读： references/accessibility.md

在用户需要以下功能时：

• 确保符合 WCAG 2.2 和 Section 508 标准
• 了解应用于轮播的 WAI-ARIA 属性
• 配置键盘导航
• 了解键盘快捷键（方向键、Home、End、Space、Enter）
• 启用或禁用键盘交互
• 支持辅助技术

动画和过渡效果

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

在用户需要以下功能时：

• 应用内置动画效果（Slide 或 Fade）
• 使用 CSS 创建自定义动画
• 为每张幻灯片设置不同的时间间隔
• 启用或禁用自动播放
• 配置悬停时暂停行为
• 控制幻灯片的无限循环
• 处理幻灯片切换事件
• 启用或禁用触控滑动
• 配置滑动模式（Touch、Mouse 或两者）

样式与外观

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

当用户需要：

• 了解 CSS 类结构
• 自定义指示器的外观和间距
• 修改导航器的位置和样式
• 调整部分幻灯片的尺寸
• 覆盖默认轮播样式
• 使用 Theme Studio 创建自定义主题

快速入门示例

以下是一个包含图片幻灯片的最简轮播实现：

@using Syncfusion.Blazor.Navigations

<SfCarousel>
    <CarouselItem>
        <figure>
            <img src="images/bridge.png" alt="Bridge" style="height:100%;width:100%;" />
            <figcaption>Golden Gate Bridge</figcaption>
        </figure>
    </CarouselItem>
    <CarouselItem>
        <figure>
            <img src="images/trees.png" alt="Trees" style="height:100%;width:100%;" />
            <figcaption>Spring Flower Trees</figcaption>
        </figure>
    </CarouselItem>
    <CarouselItem>
        <figure>
            <img src="images/waterfall.png" alt="Waterfall" style="height:100%;width:100%;" />
            <figcaption>Oddadalen Waterfalls</figcaption>
        </figure>
    </CarouselItem>
</SfCarousel>

前提条件： 确保已安装 Syncfusion.Blazor.Navigations 包，并已在 Program.cs 中注册 Syncfusion Blazor 服务。有关设置详情，请参阅入门指南。

常见模式

模式 1：悬停时暂停的自动播放轮播

<SfCarousel AutoPlay="true" 
            PauseOnHover="true" 
            Interval="3000">
    <CarouselItem>
        <div>Slide 1 Content</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 2 Content</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 3 Content</div>
    </CarouselItem>
</SfCarousel>

适用场景： 产品展示、促销横幅等需要自动轮播，同时允许用户悬停暂停的场景。

模式 2：隐藏导航器并显示进度指示器的轮播

<SfCarousel ButtonsVisibility="CarouselButtonVisibility.Hidden"
            IndicatorsType="CarouselIndicatorType.Progress"
            ShowIndicators="true">
    <CarouselItem>
        <div>Slide 1</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 2</div>
    </CarouselItem>
    <CarouselItem>
        <div>Slide 3</div>
    </CarouselItem>
</SfCarousel>

适用场景： 简洁的极简设计，通过进度条显示幻灯片位置，适合依赖触摸滑动的移动端优先设计。

模式 3：部分可见的幻灯片（预览模式）

<SfCarousel PartialVisible="true" 
            Loop="true">
    <CarouselItem>
        <img src="images/image1.png" alt="Image 1" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image2.png" alt="Image 2" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image3.png" alt="Image 3" />
    </CarouselItem>
    <CarouselItem>
        <img src="images/image4.png" alt="Image 4" />
    </CarouselItem>
</SfCarousel>

适用场景： 图片库中显示相邻幻灯片可提供上下文并鼓励用户导航。

模式 4：通过按钮进行程序化导航

@using Syncfusion.Blazor.Navigations
@using Syncfusion.Blazor.Buttons

<SfCarousel @ref="CarouselRef" 
            ButtonsVisibility="CarouselButtonVisibility.Hidden">
    <CarouselItem><div>Slide 1</div></CarouselItem>
    <CarouselItem><div>Slide 2</div></CarouselItem>
    <CarouselItem><div>Slide 3</div></CarouselItem>
</SfCarousel>

<div class="custom-controls">
    <SfButton @onclick="@(async () => await CarouselRef.PreviousAsync())">Previous</SfButton>
    <SfButton @onclick="@(async () => await CarouselRef.NextAsync())">Next</SfButton>
</div>

@code {
    SfCarousel CarouselRef;
}

适用场景： 需要将外部导航控件与轮播组件分离的自定义 UI 设计。

模式 5：使用自定义间隔的淡入淡出动画

<SfCarousel AnimationEffect="CarouselAnimationEffect.Fade">
    <CarouselItem Interval="2000">
        <div>Quick Slide (2s)</div>
    </CarouselItem>
    <CarouselItem Interval="4000">
        <div>Medium Slide (4s)</div>
    </CarouselItem>
    <CarouselItem Interval="6000">
        <div>Long Slide (6s)</div>
    </CarouselItem>
</SfCarousel>

适用场景： 内容复杂程度不一、部分幻灯片需要更长浏览时间的场景。

模式 6：绑定选中索引的轮播

<SfCarousel @bind-SelectedIndex="@CurrentSlide">
    <CarouselItem><div>Slide 1</div></CarouselItem>
    <CarouselItem><div>Slide 2</div></CarouselItem>
    <CarouselItem><div>Slide 3</div></CarouselItem>
</SfCarousel>

<p>Current Slide: @CurrentSlide</p>

@code {
    private int CurrentSlide = 0;
}

适用场景： 跟踪当前幻灯片位置、同步多个轮播，或根据幻灯片变化触发操作。

关键属性参考

属性	类型	默认值	描述
AutoPlay	bool	true	启用幻灯片自动切换
AnimationEffect	CarouselAnimationEffect	Slide	幻灯片切换动画（Slide、Fade、Custom、None）
ButtonsVisibility	CarouselButtonVisibility	Visible	导航器按钮的可见性（Visible、Hidden、VisibleOnHover）
EnableTouchSwipe	bool	true	在触摸设备上启用滑动手势
Interval	int	5000	幻灯片切换的默认间隔时间（ms）
Loop	bool	true	启用幻灯片无限循环
PartialVisible	bool	false	显示相邻幻灯片的部分内容
PauseOnHover	bool	true	悬停时暂停自动播放
SelectedIndex	int	0	当前活动幻灯片的索引
ShowIndicators	bool	true	显示/隐藏位置指示器
ShowPlayButton	bool	false	显示播放/暂停切换按钮
IndicatorsType	CarouselIndicatorType	Default	指示器样式（Default、Dynamic、Fraction、Progress）
SwipeMode	CarouselSwipeMode	Touch & Mouse	滑动输入模式
AllowKeyboardInteraction	bool	true	启用键盘导航

常见用例

1. 电商产品图片库： 显示多张产品图片并提供导航
2. 主视觉横幅： 在着陆页轮播促销内容
3. 客户评价滑块： 轮播展示客户评价
4. 前后对比展示： 通过幻灯片切换比较图片
5. 作品集展示： 展示项目图片或案例研究
6. 新闻/文章精选： 轮播展示精选内容
7. 引导教程： 逐步展示指南幻灯片
8. 图片灯箱： 全屏查看图片并提供导航

后续步骤

• 设置和安装 → 阅读 入门指南
• 项目管理 → 阅读 填充项目
• UI 自定义 → 阅读 导航器和指示器
• 无障碍合规 → 阅读 无障碍
• 动画 → 阅读 动画和过渡
• 样式 → 阅读 样式和外观