syncfusion-angular-carousel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Angular Carousel Component

实现Syncfusion Angular Carousel组件

When to Use This Skill

何时使用此组件

Use the Syncfusion Angular Carousel component when you need to:

Display multiple items sequentially – Show images, products, or content in slide show format
Create image galleries – Build responsive photo galleries with automatic or manual navigation
Feature rotating content – Display featured articles, product highlights, or promotional banners
Implement scroll-like navigation – Provide next/previous controls for content browsing
Add animations and transitions – Create visually appealing slide effects with fade or slide animations
Support touch interactions – Enable swipe gestures for mobile and touch devices
Display progress indicators – Show users their position within carousel (dots, fractions, progress bars)
Handle slide change events – Execute custom logic when slides transition

在以下场景中使用Syncfusion Angular Carousel组件：

按顺序展示多个项目 – 以幻灯片形式展示图片、产品或内容
创建图片画廊 – 构建支持自动或手动导航的响应式照片画廊
展示轮播内容 – 展示精选文章、产品亮点或宣传横幅
实现类滚动导航 – 提供上一页/下一页控件用于内容浏览
添加动画与过渡效果 – 创建带有淡入淡出或滑动动画的视觉吸引力幻灯片效果
支持触摸交互 – 为移动设备和触控设备启用滑动手势
显示进度指示器 – 向用户展示其在轮播中的位置（点、分数、进度条）
处理幻灯片切换事件 – 在幻灯片过渡时执行自定义逻辑

Component Overview

组件概述

The Syncfusion Angular Carousel component allows users to display images with content, links, and other media in a slide show format. It provides:

Multiple indicator types – Default dots, dynamic markers, fractions, progress bars
Built-in animations – None, Slide, Fade, and custom animation support
Navigation controls – Previous/next buttons with visibility options (Visible, Hidden, VisibleOnHover)
Touch support – Swipe gestures for mobile and desktop navigation
Auto-play functionality – Automatic slide transitions with configurable intervals
Keyboard accessibility – Arrow key navigation and WAI-ARIA compliance
Template support – Custom item rendering, button templates, indicator customization
Event handling – Pre/post slide transition events (slideChanging, slideChanged) for custom logic
Persistence – Save/restore carousel state across page reloads
RTL support – Right-to-left layout for Arabic, Hebrew, and other RTL languages

Syncfusion Angular Carousel组件允许用户以幻灯片形式展示包含图片、内容、链接和其他媒体的内容。它提供：

多种指示器类型 – 默认点标记、动态标记、分数、进度条
内置动画 – 无动画、滑动、淡入淡出，以及自定义动画支持
导航控件 – 上一页/下一页按钮，支持可见性选项（Visible、Hidden、VisibleOnHover）
触摸支持 – 适用于移动设备和桌面设备的滑动手势
自动播放功能 – 可配置间隔的自动幻灯片过渡
键盘可访问性 – 方向键导航和WAI-ARIA合规性
模板支持 – 自定义项渲染、按钮模板、指示器定制
事件处理 – 幻灯片过渡前后的事件（slideChanging、slideChanged），用于执行自定义逻辑
状态持久化 – 在页面重新加载时保存/恢复轮播状态
RTL支持 – 适用于阿拉伯语、希伯来语等RTL语言的从右到左布局

Quick Start Example

快速入门示例

Basic carousel with automatic slide transitions:

typescript

import { Component } from "@angular/core";
import { CarouselModule } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel",
  standalone: true,
  imports: [CarouselModule],
  template: `
    <div class="carousel-container">
      <ejs-carousel [autoPlay]="true" [animationEffect]="'Slide'">
        <e-carousel-items>
          <e-carousel-item>
            <ng-template #template>
              <figure class="img-container">
                <img src="https://ej2.syncfusion.com/products/images/carousel/cardinal.png" alt="Slide 1" />
                <figcaption>Cardinal</figcaption>
              </figure>
            </ng-template>
          </e-carousel-item>
          <e-carousel-item>
            <ng-template #template>
              <figure class="img-container">
                <img src="https://ej2.syncfusion.com/products/images/carousel/hunei.png" alt="Slide 2" />
                <figcaption>Kingfisher</figcaption>
              </figure>
            </ng-template>
          </e-carousel-item>
          <e-carousel-item>
            <ng-template #template>
              <figure class="img-container">
                <img src="https://ej2.syncfusion.com/products/images/carousel/costa-rica.png" alt="Slide 3" />
                <figcaption>Keel-billed Toucan</figcaption>
              </figure>
            </ng-template>
          </e-carousel-item>
        </e-carousel-items>
      </ejs-carousel>
    </div>
  `,
  styles: [`
    .carousel-container {
      height: 400px;
      margin: 20px 0;
    }
  `]
})
export class CarouselComponent {}

Key result: Carousel automatically transitions between slides every 5000ms with slide animation.

带有自动幻灯片过渡的基础轮播：

typescript

import { Component } from "@angular/core";
import { CarouselModule } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel",
  standalone: true,
  imports: [CarouselModule],
  template: `
    <div class="carousel-container">
      <ejs-carousel [autoPlay]="true" [animationEffect]="'Slide'">
        <e-carousel-items>
          <e-carousel-item>
            <ng-template #template>
              <figure class="img-container">
                <img src="https://ej2.syncfusion.com/products/images/carousel/cardinal.png" alt="Slide 1" />
                <figcaption>Cardinal</figcaption>
              </figure>
            </ng-template>
          </e-carousel-item>
          <e-carousel-item>
            <ng-template #template>
              <figure class="img-container">
                <img src="https://ej2.syncfusion.com/products/images/carousel/hunei.png" alt="Slide 2" />
                <figcaption>Kingfisher</figcaption>
              </figure>
            </ng-template>
          </e-carousel-item>
          <e-carousel-item>
            <ng-template #template>
              <figure class="img-container">
                <img src="https://ej2.syncfusion.com/products/images/carousel/costa-rica.png" alt="Slide 3" />
                <figcaption>Keel-billed Toucan</figcaption>
              </figure>
            </ng-template>
          </e-carousel-item>
        </e-carousel-items>
      </ejs-carousel>
    </div>
  `,
  styles: [`
    .carousel-container {
      height: 400px;
      margin: 20px 0;
    }
  `]
})
export class CarouselComponent {}

关键效果： 轮播会每5000毫秒自动切换幻灯片，并带有滑动动画。

Component Properties

组件属性

30 Total Properties Organized by Category

按类别划分的30个属性

1. Core Animation Properties

1. 核心动画属性

animationEffect

Type:
```
'None' | 'Slide' | 'Fade' | 'Custom'
```
Default:
```
'Slide'
```
Description: Specifies animation effect when transitioning between slides.

typescript

// Fade animation
<ejs-carousel [animationEffect]="'Fade'">
  <!-- Smooth fade in/out between slides -->
</ejs-carousel>

// No animation
<ejs-carousel [animationEffect]="'None'">
  <!-- Instant slide transition -->
</ejs-carousel>

// Custom CSS animation
<ejs-carousel [animationEffect]="'Custom'" [cssClass]="'custom-animation'">
  <!-- Define custom animation in CSS -->
</ejs-carousel>

animationEffect

类型：
```
'None' | 'Slide' | 'Fade' | 'Custom'
```
默认值：
```
'Slide'
```
描述： 指定幻灯片过渡时的动画效果。

typescript

// 淡入淡出动画
<ejs-carousel [animationEffect]="'Fade'">
  <!-- 幻灯片间平滑淡入淡出 -->
</ejs-carousel>

// 无动画
<ejs-carousel [animationEffect]="'None'">
  <!-- 即时切换幻灯片 -->
</ejs-carousel>

// 自定义CSS动画
<ejs-carousel [animationEffect]="'Custom'" [cssClass]="'custom-animation'">
  <!-- 在CSS中定义自定义动画 -->
</ejs-carousel>

2. Auto-Play Properties

2. 自动播放属性

autoPlay

Type:
```
boolean
```
Default:
```
true
```
Description: Enables automatic sliding through carousel items at intervals.

typescript

<ejs-carousel [autoPlay]="true" [interval]="3000">
  <!-- Auto transitions every 3 seconds -->
</ejs-carousel>

interval

Type:
```
number
```
Default:
```
5000
```
(milliseconds)
Description: Time between automatic slide transitions (milliseconds). Only applies when autoPlay is true.

typescript

<ejs-carousel [autoPlay]="true" [interval]="2000">
  <!-- 2 second interval between slides -->
</ejs-carousel>

pauseOnHover

Type:
```
boolean
```
Default:
```
true
```
Description: Pauses auto-play when mouse hovers over carousel.

typescript

<ejs-carousel [autoPlay]="true" [pauseOnHover]="false">
  <!-- Continue auto-play even on hover -->
</ejs-carousel>

autoPlay

类型：
```
boolean
```
默认值：
```
true
```
描述： 启用自动按间隔切换轮播项。

typescript

<ejs-carousel [autoPlay]="true" [interval]="3000">
  <!-- 每3秒自动切换 -->
</ejs-carousel>

interval

类型：
```
number
```
默认值：
```
5000
```
（毫秒）
描述： 自动幻灯片过渡的时间间隔（毫秒）。仅在autoPlay为true时生效。

typescript

<ejs-carousel [autoPlay]="true" [interval]="2000">
  <!-- 幻灯片间隔2秒 -->
</ejs-carousel>

pauseOnHover

类型：
```
boolean
```
默认值：
```
true
```
描述： 当鼠标悬停在轮播上时暂停自动播放。

typescript

<ejs-carousel [autoPlay]="true" [pauseOnHover]="false">
  <!-- 即使悬停也继续自动播放 -->
</ejs-carousel>

3. Navigation Properties

3. 导航属性

buttonsVisibility

Type:
```
'Visible' | 'Hidden' | 'VisibleOnHover'
```
Default:
```
'Visible'
```
Description: Controls visibility of previous/next navigation buttons.

typescript

// Always visible
<ejs-carousel [buttonsVisibility]="'Visible'">
  <!-- Buttons always shown -->
</ejs-carousel>

// Only on hover
<ejs-carousel [buttonsVisibility]="'VisibleOnHover'">
  <!-- Buttons appear on mouse hover -->
</ejs-carousel>

// Never visible
<ejs-carousel [buttonsVisibility]="'Hidden'">
  <!-- Use indicators or swipe instead -->
</ejs-carousel>

previousButtonTemplate

Type:
```
string | object
```
Default:
```
null
```
Description: Custom template for previous navigation button.

typescript

<ejs-carousel [previousButtonTemplate]="'#prevBtnTemplate'">
  <ng-template #prevBtnTemplate>
    <button class="custom-prev"><i class="icon-left"></i> Back</button>
  </ng-template>
  <e-carousel-items><!-- Items --></e-carousel-items>
</ejs-carousel>

nextButtonTemplate

Type:
```
string | object
```
Default:
```
null
```
Description: Custom template for next navigation button.

typescript

<ejs-carousel [nextButtonTemplate]="'#nextBtnTemplate'">
  <ng-template #nextBtnTemplate>
    <button class="custom-next">Next <i class="icon-right"></i></button>
  </ng-template>
  <e-carousel-items><!-- Items --></e-carousel-items>
</ejs-carousel>

loop

Type:
```
boolean
```
Default:
```
true
```
Description: Enables infinite looping - cycles back to first slide after last.

typescript

<ejs-carousel [loop]="true">
  <!-- Last slide -> First slide -->
</ejs-carousel>

<ejs-carousel [loop]="false">
  <!-- Last slide -> Navigation stops -->
</ejs-carousel>

selectedIndex

Type:
```
number
```
Default:
```
0
```
Description: Initial slide index to display (0-based).

typescript

<ejs-carousel [selectedIndex]="2">
  <!-- Start on third slide (index 2) -->
</ejs-carousel>

buttonsVisibility

类型：
```
'Visible' | 'Hidden' | 'VisibleOnHover'
```
默认值：
```
'Visible'
```
描述： 控制上一页/下一页导航按钮的可见性。

typescript

// 始终可见
<ejs-carousel [buttonsVisibility]="'Visible'">
  <!-- 按钮始终显示 -->
</ejs-carousel>

// 仅在悬停时可见
<ejs-carousel [buttonsVisibility]="'VisibleOnHover'">
  <!-- 鼠标悬停时显示按钮 -->
</ejs-carousel>

// 始终隐藏
<ejs-carousel [buttonsVisibility]="'Hidden'">
  <!-- 使用指示器或滑动进行导航 -->
</ejs-carousel>

previousButtonTemplate

类型：
```
string | object
```
默认值：
```
null
```
描述： 上一页导航按钮的自定义模板。

typescript

<ejs-carousel [previousButtonTemplate]="'#prevBtnTemplate'">
  <ng-template #prevBtnTemplate>
    <button class="custom-prev"><i class="icon-left"></i> Back</button>
  </ng-template>
  <e-carousel-items><!-- 轮播项 --></e-carousel-items>
</ejs-carousel>

nextButtonTemplate

类型：
```
string | object
```
默认值：
```
null
```
描述： 下一页导航按钮的自定义模板。

typescript

<ejs-carousel [nextButtonTemplate]="'#nextBtnTemplate'">
  <ng-template #nextBtnTemplate>
    <button class="custom-next">Next <i class="icon-right"></i></button>
  </ng-template>
  <e-carousel-items><!-- 轮播项 --></e-carousel-items>
</ejs-carousel>

loop

类型：
```
boolean
```
默认值：
```
true
```
描述： 启用无限循环 - 最后一张幻灯片后循环回到第一张。

typescript

<ejs-carousel [loop]="true">
  <!-- 最后一张幻灯片 → 第一张幻灯片 -->
</ejs-carousel>

<ejs-carousel [loop]="false">
  <!-- 最后一张幻灯片 → 导航停止 -->
</ejs-carousel>

selectedIndex

类型：
```
number
```
默认值：
```
0
```
描述： 初始显示的幻灯片索引（从0开始）。

typescript

<ejs-carousel [selectedIndex]="2">
  <!-- 从第三张幻灯片开始（索引2） -->
</ejs-carousel>

4. Indicator Properties

4. 指示器属性

showIndicators

Type:
```
boolean
```
Default:
```
true
```
Description: Shows or hides position indicators.

typescript

<ejs-carousel [showIndicators]="true">
  <!-- Indicators visible -->
</ejs-carousel>

<ejs-carousel [showIndicators]="false">
  <!-- No indicators shown -->
</ejs-carousel>

indicatorsType

Type:

'Default' | 'Dynamic' | 'Fraction' | 'Progress'

Default:
```
'Default'
```
Description: Style of indicators displayed.

typescript

// Dot indicators
<ejs-carousel [indicatorsType]="'Default'">
  <!-- Shows: ● ● ● ● ● -->
</ejs-carousel>

// Numeric format
<ejs-carousel [indicatorsType]="'Fraction'">
  <!-- Shows: 1 / 5 -->
</ejs-carousel>

// Progress bar
<ejs-carousel [indicatorsType]="'Progress'">
  <!-- Visual progress bar -->
</ejs-carousel>

// Animated
<ejs-carousel [indicatorsType]="'Dynamic'">
  <!-- Animated indicator effect -->
</ejs-carousel>

indicatorsTemplate

Type:
```
string | object
```
Default:
```
null
```
Description: Custom template for indicators (e.g., thumbnail previews).

typescript

<ejs-carousel [indicatorsTemplate]="'#indicatorTemplate'" [showIndicators]="true">
  <ng-template #indicatorTemplate let-data let-index="index">
    <img [src]="items[index]?.thumbnail" class="thumb" />
  </ng-template>
  <e-carousel-items><!-- Items --></e-carousel-items>
</ejs-carousel>

showPlayButton

Type:
```
boolean
```
Default:
```
true
```
Description: Shows or hides play button to resume auto-play.

typescript

<ejs-carousel [autoPlay]="false" [showPlayButton]="true">
  <!-- Users can click play to resume auto-play -->
</ejs-carousel>

<ejs-carousel [showPlayButton]="false">
  <!-- No play button visible -->
</ejs-carousel>

playButtonTemplate

Type:
```
string | object
```
Default:
```
null
```
Description: Custom template for play button.

typescript

<ejs-carousel [playButtonTemplate]="'#playBtnTemplate'">
  <ng-template #playBtnTemplate>
    <button class="play-btn">▶ Resume</button>
  </ng-template>
  <e-carousel-items><!-- Items --></e-carousel-items>
</ejs-carousel>

showIndicators

类型：
```
boolean
```
默认值：
```
true
```
描述： 显示或隐藏位置指示器。

typescript

<ejs-carousel [showIndicators]="true">
  <!-- 指示器可见 -->
</ejs-carousel>

<ejs-carousel [showIndicators]="false">
  <!-- 不显示指示器 -->
</ejs-carousel>

indicatorsType

类型：

'Default' | 'Dynamic' | 'Fraction' | 'Progress'

默认值：
```
'Default'
```
描述： 显示的指示器样式。

typescript

// 点指示器
<ejs-carousel [indicatorsType]="'Default'">
  <!-- 显示：● ● ● ● ● -->
</ejs-carousel>

// 数字格式
<ejs-carousel [indicatorsType]="'Fraction'">
  <!-- 显示：1 / 5 -->
</ejs-carousel>

// 进度条
<ejs-carousel [indicatorsType]="'Progress'">
  <!-- 可视化进度条 -->
</ejs-carousel>

// 动画效果
<ejs-carousel [indicatorsType]="'Dynamic'">
  <!-- 动画指示器效果 -->
</ejs-carousel>

indicatorsTemplate

类型：
```
string | object
```
默认值：
```
null
```
描述： 指示器的自定义模板（例如缩略图预览）。

typescript

<ejs-carousel [indicatorsTemplate]="'#indicatorTemplate'" [showIndicators]="true">
  <ng-template #indicatorTemplate let-data let-index="index">
    <img [src]="items[index]?.thumbnail" class="thumb" />
  </ng-template>
  <e-carousel-items><!-- 轮播项 --></e-carousel-items>
</ejs-carousel>

showPlayButton

类型：
```
boolean
```
默认值：
```
true
```
描述： 显示或隐藏用于恢复自动播放的播放按钮。

typescript

<ejs-carousel [autoPlay]="false" [showPlayButton]="true">
  <!-- 用户可以点击播放恢复自动播放 -->
</ejs-carousel>

<ejs-carousel [showPlayButton]="false">
  <!-- 不显示播放按钮 -->
</ejs-carousel>

playButtonTemplate

类型：
```
string | object
```
默认值：
```
null
```
描述： 播放按钮的自定义模板。

typescript

<ejs-carousel [playButtonTemplate]="'#playBtnTemplate'">
  <ng-template #playBtnTemplate>
    <button class="play-btn">▶ Resume</button>
  </ng-template>
  <e-carousel-items><!-- 轮播项 --></e-carousel-items>
</ejs-carousel>

5. Data and Item Properties

5. 数据与项属性

dataSource

Type:
```
any[]
```
Default:
```
null
```
Description: Array of data for dynamic carousel items (use with itemTemplate).

typescript

// Component
export class CarouselComponent {
  public slides = [
    { id: 1, image: 'img1.jpg', title: 'Slide 1' },
    { id: 2, image: 'img2.jpg', title: 'Slide 2' },
    { id: 3, image: 'img3.jpg', title: 'Slide 3' }
  ];
}

// Template
<ejs-carousel [dataSource]="slides">
  <ng-template #itemTemplate let-item>
    <figure>
      <img [src]="item.image" [alt]="item.title" />
      <figcaption>{{item.title}}</figcaption>
    </figure>
  </ng-template>
</ejs-carousel>

itemTemplate

Type:
```
string | object
```
Default:
```
null
```
Description: Template for rendering each carousel item from dataSource.

typescript

<ejs-carousel [dataSource]="products">
  <ng-template #itemTemplate let-product>
    <div class="product-card">
      <img [src]="product.image" />
      <h3>{{product.name}}</h3>
      <p>${{product.price}}</p>
    </div>
  </ng-template>
</ejs-carousel>

items

Type:
```
CarouselItem[]
```
Default:
```
[]
```
Description: Array of carousel items (use with e-carousel-item directive for static content).

typescript

<ejs-carousel>
  <e-carousel-items>
    <e-carousel-item>
      <ng-template #template><img src="image1.jpg" /></ng-template>
    </e-carousel-item>
    <e-carousel-item>
      <ng-template #template><img src="image2.jpg" /></ng-template>
    </e-carousel-item>
  </e-carousel-items>
</ejs-carousel>

cssClass

Type:
```
string
```
Default:
```
''
```
Description: CSS class(es) for carousel container styling.

typescript

<ejs-carousel [cssClass]="'dark-theme full-width'">
  <!-- Apply custom styles via CSS classes -->
</ejs-carousel>

dataSource

类型：
```
any[]
```
默认值：
```
null
```
描述： 动态轮播项的数据源数组（与itemTemplate配合使用）。

typescript

// 组件
export class CarouselComponent {
  public slides = [
    { id: 1, image: 'img1.jpg', title: 'Slide 1' },
    { id: 2, image: 'img2.jpg', title: 'Slide 2' },
    { id: 3, image: 'img3.jpg', title: 'Slide 3' }
  ];
}

// 模板
<ejs-carousel [dataSource]="slides">
  <ng-template #itemTemplate let-item>
    <figure>
      <img [src]="item.image" [alt]="item.title" />
      <figcaption>{{item.title}}</figcaption>
    </figure>
  </ng-template>
</ejs-carousel>

itemTemplate

类型：
```
string | object
```
默认值：
```
null
```
描述： 用于渲染dataSource中每个轮播项的模板。

typescript

<ejs-carousel [dataSource]="products">
  <ng-template #itemTemplate let-product>
    <div class="product-card">
      <img [src]="product.image" />
      <h3>{{product.name}}</h3>
      <p>${{product.price}}</p>
    </div>
  </ng-template>
</ejs-carousel>

items

类型：
```
CarouselItem[]
```
默认值：
```
[]
```
描述： 轮播项数组（与e-carousel-item指令配合用于静态内容）。

typescript

<ejs-carousel>
  <e-carousel-items>
    <e-carousel-item>
      <ng-template #template><img src="image1.jpg" /></ng-template>
    </e-carousel-item>
    <e-carousel-item>
      <ng-template #template><img src="image2.jpg" /></ng-template>
    </e-carousel-item>
  </e-carousel-items>
</ejs-carousel>

cssClass

类型：
```
string
```
默认值：
```
''
```
描述： 用于轮播容器样式的CSS类。

typescript

<ejs-carousel [cssClass]="'dark-theme full-width'">
  <!-- 通过CSS类应用自定义样式 -->
</ejs-carousel>

6. Interaction Properties

6. 交互属性

enableTouchSwipe

Type:
```
boolean
```
Default:
```
true
```
Description: Enables swiping on touch devices to navigate slides.

typescript

<ejs-carousel [enableTouchSwipe]="true">
  <!-- Touch swipe enabled -->
</ejs-carousel>

<ejs-carousel [enableTouchSwipe]="false">
  <!-- Touch swipe disabled -->
</ejs-carousel>

swipeMode

Type:
```
'Touch' | 'Mouse' | 'Touch|Mouse'
```
Default:
```
'Touch|Mouse'
```
Description: Which interaction types enable swiping.

typescript

// Both touch and mouse
<ejs-carousel [swipeMode]="'Touch|Mouse'" [enableTouchSwipe]="true">
  <!-- Both interactions work -->
</ejs-carousel>

// Touch only
<ejs-carousel [swipeMode]="'Touch'" [enableTouchSwipe]="true">
  <!-- Only touch gestures work -->
</ejs-carousel>

// Mouse only
<ejs-carousel [swipeMode]="'Mouse'" [enableTouchSwipe]="true">
  <!-- Only mouse drag works -->
</ejs-carousel>

allowKeyboardInteraction

Type:
```
boolean
```
Default:
```
true
```
Description: Allows arrow keys to navigate carousel.

typescript

<ejs-carousel [allowKeyboardInteraction]="true">
  <!-- Arrow keys navigate slides -->
</ejs-carousel>

<ejs-carousel [allowKeyboardInteraction]="false">
  <!-- Arrow keys disabled -->
</ejs-carousel>

enableTouchSwipe

类型：
```
boolean
```
默认值：
```
true
```
描述： 启用触控设备上的滑动导航功能。

typescript

<ejs-carousel [enableTouchSwipe]="true">
  <!-- 启用触摸滑动 -->
</ejs-carousel>

<ejs-carousel [enableTouchSwipe]="false">
  <!-- 禁用触摸滑动 -->
</ejs-carousel>

swipeMode

类型：
```
'Touch' | 'Mouse' | 'Touch|Mouse'
```
默认值：
```
'Touch|Mouse'
```
描述： 哪些交互类型支持滑动。

typescript

// 触摸和鼠标都支持
<ejs-carousel [swipeMode]="'Touch|Mouse'" [enableTouchSwipe]="true">
  <!-- 两种交互方式都有效 -->
</ejs-carousel>

// 仅支持触摸
<ejs-carousel [swipeMode]="'Touch'" [enableTouchSwipe]="true">
  <!-- 仅触摸手势有效 -->
</ejs-carousel>

// 仅支持鼠标
<ejs-carousel [swipeMode]="'Mouse'" [enableTouchSwipe]="true">
  <!-- 仅鼠标拖动有效 -->
</ejs-carousel>

allowKeyboardInteraction

类型：
```
boolean
```
默认值：
```
true
```
描述： 允许使用方向键导航轮播。

typescript

<ejs-carousel [allowKeyboardInteraction]="true">
  <!-- 方向键可导航幻灯片 -->
</ejs-carousel>

<ejs-carousel [allowKeyboardInteraction]="false">
  <!-- 禁用方向键导航 -->
</ejs-carousel>

7. Dimension Properties

7. 尺寸属性

height

Type:
```
string | number
```
Default:
```
'100%'
```
Description: Carousel container height (px, %, em, etc.).

typescript

// Fixed height
<ejs-carousel [height]="400">
  <!-- 400px height -->
</ejs-carousel>

// Percentage
<ejs-carousel [height]="'100%'">
  <!-- Full parent height -->
</ejs-carousel>

width

Type:
```
string | number
```
Default:
```
'100%'
```
Description: Carousel container width (px, %, em, etc.).

typescript

// Fixed width
<ejs-carousel [width]="800">
  <!-- 800px width -->
</ejs-carousel>

// Full width
<ejs-carousel [width]="'100%'">
  <!-- Full parent width -->
</ejs-carousel>

partialVisible

Type:
```
boolean
```
Default:
```
false
```
Description: Shows partial slides on sides for context.

typescript

<ejs-carousel [partialVisible]="true">
  <!-- Shows portion of adjacent slides -->
</ejs-carousel>

<ejs-carousel [partialVisible]="false">
  <!-- Only current slide fully visible -->
</ejs-carousel>

height

类型：
```
string | number
```
默认值：
```
'100%'
```
描述： 轮播容器的高度（px、%、em等）。

typescript

// 固定高度
<ejs-carousel [height]="400">
  <!-- 高度400px -->
</ejs-carousel>

// 百分比高度
<ejs-carousel [height]="'100%'">
  <!-- 占父容器全部高度 -->
</ejs-carousel>

width

类型：
```
string | number
```
默认值：
```
'100%'
```
描述： 轮播容器的宽度（px、%、em等）。

typescript

// 固定宽度
<ejs-carousel [width]="800">
  <!-- 宽度800px -->
</ejs-carousel>

// 全宽
<ejs-carousel [width]="'100%'">
  <!-- 占父容器全部宽度 -->
</ejs-carousel>

partialVisible

类型：
```
boolean
```
默认值：
```
false
```
描述： 在两侧显示部分幻灯片以提供上下文。

typescript

<ejs-carousel [partialVisible]="true">
  <!-- 显示相邻幻灯片的部分内容 -->
</ejs-carousel>

<ejs-carousel [partialVisible]="false">
  <!-- 仅当前幻灯片完全可见 -->
</ejs-carousel>

8. Localization and Persistence

8. 本地化与持久化

locale

Type:
```
string
```
Default:
```
''
```
(uses browser locale)
Description: Locale/language for carousel (affects aria-labels, accessibility text).

typescript

<ejs-carousel [locale]="'de-DE'">
  <!-- German localization -->
</ejs-carousel>

<ejs-carousel [locale]="'fr-FR'">
  <!-- French localization -->
</ejs-carousel>

enablePersistence

Type:
```
boolean
```
Default:
```
false
```
Description: Saves carousel state to localStorage (restores on page reload).

typescript

<ejs-carousel [enablePersistence]="true">
  <!-- Current slide position saved and restored -->
</ejs-carousel>

locale

类型：
```
string
```
默认值：
```
''
```
（使用浏览器区域设置）
描述： 轮播的区域设置/语言（影响aria标签、可访问性文本）。

typescript

<ejs-carousel [locale]="'de-DE'">
  <!-- 德语本地化 -->
</ejs-carousel>

<ejs-carousel [locale]="'fr-FR'">
  <!-- 法语本地化 -->
</ejs-carousel>

enablePersistence

类型：
```
boolean
```
默认值：
```
false
```
描述： 将轮播状态保存到localStorage（页面重新加载时恢复）。

typescript

<ejs-carousel [enablePersistence]="true">
  <!-- 当前幻灯片位置会被保存并恢复 -->
</ejs-carousel>

9. Accessibility Properties

9. 可访问性属性

enableRtl

Type:
```
boolean
```
Default:
```
false
```
Description: Enables right-to-left layout for RTL languages.

typescript

<ejs-carousel [enableRtl]="true">
  <!-- RTL layout for Arabic, Hebrew, etc. -->
</ejs-carousel>

htmlAttributes

Type:
```
Record<string, any>
```
Default:
```
null
```
Description: Additional HTML attributes for carousel root element.

typescript

<ejs-carousel [htmlAttributes]="{ 'data-type': 'hero', 'aria-label': 'Hero Carousel' }">
  <!-- Custom attributes applied -->
</ejs-carousel>

enableRtl

类型：
```
boolean
```
默认值：
```
false
```
描述： 启用RTL语言的从右到左布局。

typescript

<ejs-carousel [enableRtl]="true">
  <!-- 适用于阿拉伯语、希伯来语等的RTL布局 -->
</ejs-carousel>

htmlAttributes

类型：
```
Record<string, any>
```
默认值：
```
null
```
描述： 轮播根元素的附加HTML属性。

typescript

<ejs-carousel [htmlAttributes]="{ 'data-type': 'hero', 'aria-label': 'Hero Carousel' }">
  <!-- 应用自定义属性 -->
</ejs-carousel>

Component Methods

组件方法

5 Total Methods

共5个方法

1. next()

Signature:
```
next(): void
```
Description: Navigate to next slide programmatically.

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel-nav",
  template: `
    <button (click)="goNext()">Next</button>
    <ejs-carousel #carousel>
      <e-carousel-items>
        <e-carousel-item><ng-template #template><img src="img1.jpg" /></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img2.jpg" /></ng-template></e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class CarouselNavComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;

  goNext() {
    this.carousel.next();
  }
}

签名：
```
next(): void
```
描述： 以编程方式导航到下一张幻灯片。

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel-nav",
  template: `
    <button (click)="goNext()">Next</button>
    <ejs-carousel #carousel>
      <e-carousel-items>
        <e-carousel-item><ng-template #template><img src="img1.jpg" /></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img2.jpg" /></ng-template></e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class CarouselNavComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;

  goNext() {
    this.carousel.next();
  }
}

2. prev()

Signature:
```
prev(): void
```
Description: Navigate to previous slide programmatically.

typescript

export class CarouselNavComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;

  goPrev() {
    this.carousel.prev();
  }
}

签名：
```
prev(): void
```
描述： 以编程方式导航到上一张幻灯片。

typescript

export class CarouselNavComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;

  goPrev() {
    this.carousel.prev();
  }
}

3. play()

Signature:
```
play(): void
```
Description: Resume automatic slide transitions.

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel-controls",
  template: `
    <button (click)="playSlides()">Play</button>
    <button (click)="pauseSlides()">Pause</button>
    <ejs-carousel #carousel [autoPlay]="false">
      <e-carousel-items>
        <e-carousel-item><ng-template #template><img src="img1.jpg" /></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img2.jpg" /></ng-template></e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class CarouselControlsComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;

  playSlides() {
    this.carousel.play();
  }

  pauseSlides() {
    this.carousel.pause();
  }
}

签名：
```
play(): void
```
描述： 恢复自动幻灯片过渡。

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel-controls",
  template: `
    <button (click)="playSlides()">Play</button>
    <button (click)="pauseSlides()">Pause</button>
    <ejs-carousel #carousel [autoPlay]="false">
      <e-carousel-items>
        <e-carousel-item><ng-template #template><img src="img1.jpg" /></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img2.jpg" /></ng-template></e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class CarouselControlsComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;

  playSlides() {
    this.carousel.play();
  }

  pauseSlides() {
    this.carousel.pause();
  }
}

4. pause()

Signature:
```
pause(): void
```
Description: Pause automatic slide transitions.

typescript

export class CarouselControlsComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;

  pauseSlides() {
    this.carousel.pause();
  }
}

签名：
```
pause(): void
```
描述： 暂停自动幻灯片过渡。

typescript

export class CarouselControlsComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;

  pauseSlides() {
    this.carousel.pause();
  }
}

5. destroy()

Signature:
```
destroy(): void
```
Description: Destroy carousel component and release resources. Call before component removal.

typescript

import { Component, ViewChild, OnDestroy } from "@angular/core";
import { CarouselComponent } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel-cleanup",
  template: `
    <ejs-carousel #carousel>
      <e-carousel-items>
        <e-carousel-item><ng-template #template><img src="img1.jpg" /></ng-template></e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class CarouselCleanupComponent implements OnDestroy {
  @ViewChild("carousel") carousel!: CarouselComponent;

  ngOnDestroy() {
    // Cleanup when component destroyed
    this.carousel.destroy();
  }
}

签名：
```
destroy(): void
```
描述： 销毁轮播组件并释放资源。在组件移除前调用。

typescript

import { Component, ViewChild, OnDestroy } from "@angular/core";
import { CarouselComponent } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel-cleanup",
  template: `
    <ejs-carousel #carousel>
      <e-carousel-items>
        <e-carousel-item><ng-template #template><img src="img1.jpg" /></ng-template></e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class CarouselCleanupComponent implements OnDestroy {
  @ViewChild("carousel") carousel!: CarouselComponent;

  ngOnDestroy() {
    // 组件销毁时清理
    this.carousel.destroy();
  }
}

Component Events

组件事件

2 Total Events

共2个事件

1. slideChanging

Event Args:
```
SlideChangingEventArgs
```
Description: Triggered before slide transition (can be prevented).
Key Use: Validate or cancel slide changes

Event Arguments:

```
cancel: boolean
```
– Set true to prevent transition
```
currentIndex: number
```
– Current slide index
```
currentSlide: HTMLElement
```
– Current slide DOM element
```
nextIndex: number
```
– Next slide index to display
```
nextSlide: HTMLElement
```
– Next slide DOM element
```
isSwiped: boolean
```
– Whether triggered by swipe
```
slideDirection: 'Next' | 'Previous'
```
– Direction of change
```
name: string
```
– Event name ('slideChanging')

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent, SlideChangingEventArgs } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel-event",
  template: `
    <div class="status">Cannot navigate to slide 2</div>
    <ejs-carousel #carousel (slideChanging)="onSlideChanging($event)">
      <e-carousel-items>
        <e-carousel-item><ng-template #template><img src="img1.jpg" /><p>Slide 1</p></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img2.jpg" /><p>Slide 2 - BLOCKED</p></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img3.jpg" /><p>Slide 3</p></ng-template></e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class CarouselEventComponent {
  onSlideChanging(args: SlideChangingEventArgs) {
    console.log(`Transitioning from ${args.currentIndex} to ${args.nextIndex}`);
    
    // Prevent navigating to slide 2
    if (args.nextIndex === 1) {
      args.cancel = true;
      alert("Slide 2 is blocked");
    }
  }
}

事件参数：
```
SlideChangingEventArgs
```
描述： 在幻灯片过渡前触发（可阻止）。
主要用途： 验证或取消幻灯片切换

事件参数：

```
cancel: boolean
```
– 设置为true可阻止过渡
```
currentIndex: number
```
– 当前幻灯片索引
```
currentSlide: HTMLElement
```
– 当前幻灯片DOM元素
```
nextIndex: number
```
– 要显示的下一张幻灯片索引
```
nextSlide: HTMLElement
```
– 下一张幻灯片DOM元素
```
isSwiped: boolean
```
– 是否由滑动触发
```
slideDirection: 'Next' | 'Previous'
```
– 切换方向
```
name: string
```
– 事件名称（'slideChanging'）

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent, SlideChangingEventArgs } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel-event",
  template: `
    <div class="status">无法导航到幻灯片2</div>
    <ejs-carousel #carousel (slideChanging)="onSlideChanging($event)">
      <e-carousel-items>
        <e-carousel-item><ng-template #template><img src="img1.jpg" /><p>幻灯片1</p></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img2.jpg" /><p>幻灯片2 - 已阻止</p></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img3.jpg" /><p>幻灯片3</p></ng-template></e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class CarouselEventComponent {
  onSlideChanging(args: SlideChangingEventArgs) {
    console.log(`正在从${args.currentIndex}切换到${args.nextIndex}`);
    
    // 阻止导航到幻灯片2
    if (args.nextIndex === 1) {
      args.cancel = true;
      alert("幻灯片2已被阻止");
    }
  }
}

2. slideChanged

Event Args:
```
SlideChangedEventArgs
```
Description: Triggered after slide transition completes.
Key Use: Track slide changes, update UI, log analytics

Event Arguments:

```
currentIndex: number
```
– Current slide index
```
currentSlide: HTMLElement
```
– Current slide DOM element
```
previousIndex: number
```
– Previous slide index
```
previousSlide: HTMLElement
```
– Previous slide DOM element
```
isSwiped: boolean
```
– Whether triggered by swipe
```
slideDirection: 'Next' | 'Previous'
```
– Direction of change
```
name: string
```
– Event name ('slideChanged')

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent, SlideChangedEventArgs } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel-tracking",
  template: `
    <div class="slide-counter">Slide {{currentSlide}} of {{totalSlides}}</div>
    <ejs-carousel #carousel (slideChanged)="onSlideChanged($event)">
      <e-carousel-items>
        <e-carousel-item><ng-template #template><img src="img1.jpg" /></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img2.jpg" /></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img3.jpg" /></ng-template></e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class CarouselTrackingComponent {
  currentSlide = 1;
  totalSlides = 3;

  onSlideChanged(args: SlideChangedEventArgs) {
    this.currentSlide = args.currentIndex + 1;
    console.log(`Now on slide ${args.currentIndex}`);
    console.log(`Direction: ${args.slideDirection}`);
    console.log(`Swiped: ${args.isSwiped}`);
  }
}

事件参数：
```
SlideChangedEventArgs
```
描述： 幻灯片过渡完成后触发。
主要用途： 跟踪幻灯片变化、更新UI、记录分析数据

事件参数：

```
currentIndex: number
```
– 当前幻灯片索引
```
currentSlide: HTMLElement
```
– 当前幻灯片DOM元素
```
previousIndex: number
```
– 上一张幻灯片索引
```
previousSlide: HTMLElement
```
– 上一张幻灯片DOM元素
```
isSwiped: boolean
```
– 是否由滑动触发
```
slideDirection: 'Next' | 'Previous'
```
– 切换方向
```
name: string
```
– 事件名称（'slideChanged'）

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent, SlideChangedEventArgs } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-carousel-tracking",
  template: `
    <div class="slide-counter">第{{currentSlide}}张，共{{totalSlides}}张</div>
    <ejs-carousel #carousel (slideChanged)="onSlideChanged($event)">
      <e-carousel-items>
        <e-carousel-item><ng-template #template><img src="img1.jpg" /></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img2.jpg" /></ng-template></e-carousel-item>
        <e-carousel-item><ng-template #template><img src="img3.jpg" /></ng-template></e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class CarouselTrackingComponent {
  currentSlide = 1;
  totalSlides = 3;

  onSlideChanged(args: SlideChangedEventArgs) {
    this.currentSlide = args.currentIndex + 1;
    console.log(`当前幻灯片索引：${args.currentIndex}`);
    console.log(`切换方向：${args.slideDirection}`);
    console.log(`是否由滑动触发：${args.isSwiped}`);
  }
}

Default Values Reference

默认值参考

Complete table of default values for all 30 properties:

Property	Default	Type
allowKeyboardInteraction	true	boolean
animationEffect	'Slide'	string
autoPlay	true	boolean
buttonsVisibility	'Visible'	string
cssClass	''	string
dataSource	null	any[]
enablePersistence	false	boolean
enableRtl	false	boolean
enableTouchSwipe	true	boolean
height	'100%'	string/number
htmlAttributes	null	Record
indicatorsTemplate	null	string/object
indicatorsType	'Default'	string
interval	5000	number (ms)
itemTemplate	null	string/object
items	[]	CarouselItem[]
locale	''	string
loop	true	boolean
nextButtonTemplate	null	string/object
partialVisible	false	boolean
pauseOnHover	true	boolean
playButtonTemplate	null	string/object
previousButtonTemplate	null	string/object
selectedIndex	0	number
showIndicators	true	boolean
showPlayButton	true	boolean
swipeMode	'Touch\|Mouse'	string
width	'100%'	string/number

所有30个属性的默认值完整表格：

属性	默认值	类型
allowKeyboardInteraction	true	boolean
animationEffect	'Slide'	string
autoPlay	true	boolean
buttonsVisibility	'Visible'	string
cssClass	''	string
dataSource	null	any[]
enablePersistence	false	boolean
enableRtl	false	boolean
enableTouchSwipe	true	boolean
height	'100%'	string/number
htmlAttributes	null	Record
indicatorsTemplate	null	string/object
indicatorsType	'Default'	string
interval	5000	number (ms)
itemTemplate	null	string/object
items	[]	CarouselItem[]
locale	''	string
loop	true	boolean
nextButtonTemplate	null	string/object
partialVisible	false	boolean
pauseOnHover	true	boolean
playButtonTemplate	null	string/object
previousButtonTemplate	null	string/object
selectedIndex	0	number
showIndicators	true	boolean
showPlayButton	true	boolean
swipeMode	'Touch\|Mouse'	string
width	'100%'	string/number

Common Patterns and Use Cases

常见模式与使用场景

Pattern 1: Data-Bound Carousel with Dynamic Content

模式1：绑定动态内容的轮播

When to use: Loading carousel items from an API or dynamic data source.

typescript

import { Component, OnInit } from "@angular/core";
import { HttpClient } from "@angular/common/http";

@Component({
  selector: "app-data-carousel",
  template: `
    <ejs-carousel [dataSource]="items" [selectedIndex]="0">
      <ng-template #itemTemplate let-item>
        <figure class="img-container">
          <img [src]="item.image" [alt]="item.title" />
          <figcaption>{{item.title}}</figcaption>
        </figure>
      </ng-template>
    </ejs-carousel>
  `
})
export class DataCarouselComponent implements OnInit {
  items: any[] = [];

  constructor(private http: HttpClient) {}

  ngOnInit() {
    this.http.get<any>('/api/carousel-items')
      .subscribe(data => this.items = data);
  }
}

适用场景： 从API或动态数据源加载轮播项。

typescript

import { Component, OnInit } from "@angular/core";
import { HttpClient } from "@angular/common/http";

@Component({
  selector: "app-data-carousel",
  template: `
    <ejs-carousel [dataSource]="items" [selectedIndex]="0">
      <ng-template #itemTemplate let-item>
        <figure class="img-container">
          <img [src]="item.image" [alt]="item.title" />
          <figcaption>{{item.title}}</figcaption>
        </figure>
      </ng-template>
    </ejs-carousel>
  `
})
export class DataCarouselComponent implements OnInit {
  items: any[] = [];

  constructor(private http: HttpClient) {}

  ngOnInit() {
    this.http.get<any>('/api/carousel-items')
      .subscribe(data => this.items = data);
  }
}

Pattern 2: Manual Navigation with Buttons

模式2：带自定义按钮的手动导航

When to use: Users control slide transitions with custom buttons instead of auto-play.

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-manual-nav",
  template: `
    <div class="carousel-controls">
      <button (click)="prevSlide()" class="control-btn">← Previous</button>
      <span class="slide-counter">{{currentSlide}} / {{totalSlides}}</span>
      <button (click)="nextSlide()" class="control-btn">Next →</button>
    </div>
    <ejs-carousel 
      #carousel 
      [autoPlay]="false" 
      [buttonsVisibility]="'Hidden'"
      (slideChanged)="onSlideChanged($event)"
    >
      <e-carousel-items>
        <e-carousel-item *ngFor="let item of items">
          <ng-template #template>
            <img [src]="item.image" />
          </ng-template>
        </e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class ManualNavCarouselComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;
  
  items = [
    { image: 'image1.jpg' },
    { image: 'image2.jpg' },
    { image: 'image3.jpg' }
  ];
  
  currentSlide = 1;
  totalSlides = this.items.length;

  prevSlide() { this.carousel.prev(); }
  nextSlide() { this.carousel.next(); }

  onSlideChanged(event: any) {
    this.currentSlide = event.currentIndex + 1;
  }
}

适用场景： 用户通过自定义按钮控制幻灯片切换，而非自动播放。

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-manual-nav",
  template: `
    <div class="carousel-controls">
      <button (click)="prevSlide()" class="control-btn">← 上一页</button>
      <span class="slide-counter">{{currentSlide}} / {{totalSlides}}</span>
      <button (click)="nextSlide()" class="control-btn">下一页 →</button>
    </div>
    <ejs-carousel 
      #carousel 
      [autoPlay]="false" 
      [buttonsVisibility]="'Hidden'"
      (slideChanged)="onSlideChanged($event)"
    >
      <e-carousel-items>
        <e-carousel-item *ngFor="let item of items">
          <ng-template #template>
            <img [src]="item.image" />
          </ng-template>
        </e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class ManualNavCarouselComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;
  
  items = [
    { image: 'image1.jpg' },
    { image: 'image2.jpg' },
    { image: 'image3.jpg' }
  ];
  
  currentSlide = 1;
  totalSlides = this.items.length;

  prevSlide() { this.carousel.prev(); }
  nextSlide() { this.carousel.next(); }

  onSlideChanged(event: any) {
    this.currentSlide = event.currentIndex + 1;
  }
}

Pattern 3: Event-Driven Carousel with Custom Handlers

模式3：带自定义处理程序的事件驱动轮播

When to use: Execute custom logic on slide transitions, track analytics, or prevent certain actions.

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent, SlideChangingEventArgs, SlideChangedEventArgs } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-event-carousel",
  template: `
    <div class="carousel-stats">
      <p>Total Views: {{viewCount}}</p>
      <p>Current: {{lastViewedSlide}}</p>
    </div>
    <ejs-carousel 
      #carousel 
      (slideChanging)="onSlideChanging($event)"
      (slideChanged)="onSlideChanged($event)"
    >
      <e-carousel-items>
        <e-carousel-item *ngFor="let item of slides">
          <ng-template #template>
            <img [src]="item.image" />
            <h3>{{item.title}}</h3>
          </ng-template>
        </e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class EventCarouselComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;

  slides = [
    { title: 'Slide 1', image: 'image1.jpg' },
    { title: 'Slide 2', image: 'image2.jpg' },
    { title: 'Slide 3', image: 'image3.jpg' }
  ];

  viewCount = 0;
  lastViewedSlide = '';

  onSlideChanging(args: SlideChangingEventArgs) {
    // Example: Prevent returning to first slide
    if (args.previousIndex === 1 && args.nextIndex === 0) {
      console.log("Blocking return to first slide");
      // args.cancel = true; // Uncomment to prevent
    }
  }

  onSlideChanged(args: SlideChangedEventArgs) {
    this.viewCount++;
    this.lastViewedSlide = this.slides[args.currentIndex].title;
    
    // Log analytics
    console.log(`Viewed slide ${args.currentIndex} via ${args.slideDirection}`);
  }
}

适用场景： 在幻灯片过渡时执行自定义逻辑、跟踪分析数据或阻止特定操作。

typescript

import { Component, ViewChild } from "@angular/core";
import { CarouselComponent, SlideChangingEventArgs, SlideChangedEventArgs } from "@syncfusion/ej2-angular-navigations";

@Component({
  selector: "app-event-carousel",
  template: `
    <div class="carousel-stats">
      <p>总浏览次数：{{viewCount}}</p>
      <p>当前浏览：{{lastViewedSlide}}</p>
    </div>
    <ejs-carousel 
      #carousel 
      (slideChanging)="onSlideChanging($event)"
      (slideChanged)="onSlideChanged($event)"
    >
      <e-carousel-items>
        <e-carousel-item *ngFor="let item of slides">
          <ng-template #template>
            <img [src]="item.image" />
            <h3>{{item.title}}</h3>
          </ng-template>
        </e-carousel-item>
      </e-carousel-items>
    </ejs-carousel>
  `
})
export class EventCarouselComponent {
  @ViewChild("carousel") carousel!: CarouselComponent;

  slides = [
    { title: '幻灯片1', image: 'image1.jpg' },
    { title: '幻灯片2', image: 'image2.jpg' },
    { title: '幻灯片3', image: 'image3.jpg' }
  ];

  viewCount = 0;
  lastViewedSlide = '';

  onSlideChanging(args: SlideChangingEventArgs) {
    // 示例：阻止返回第一张幻灯片
    if (args.previousIndex === 1 && args.nextIndex === 0) {
      console.log("阻止返回第一张幻灯片");
      // args.cancel = true; // 取消注释以启用阻止
    }
  }

  onSlideChanged(args: SlideChangedEventArgs) {
    this.viewCount++;
    this.lastViewedSlide = this.slides[args.currentIndex].title;
    
    // 记录分析数据
    console.log(`通过${args.slideDirection}方式浏览了幻灯片${args.currentIndex}`);
  }
}

Implementation Guides

实现指南

For detailed implementation on specific topics, see:

Getting Started – Installation, setup, CSS imports, basic configuration
Item Population & Data – dataSource, templates, data binding, navigation
Navigation & Indicators – Button controls, indicator types, customization
Animations & Transitions – Animation effects, auto-play, event handling
Styling & Appearance – CSS customization, themes, WebP, responsive

有关特定主题的详细实现，请参阅：

入门指南 – 安装、设置、CSS导入、基础配置
项填充与数据 – dataSource、模板、数据绑定、导航
导航与指示器 – 按钮控件、指示器类型、自定义
动画与过渡 – 动画效果、自动播放、事件处理
样式与外观 – CSS自定义、主题、WebP、响应式设计

Next Steps

下一步

Choose your data approach: Use items binding for static content, dataSource for dynamic data
Select navigation style: Buttons, indicators, or both
Decide on animations: None, Slide (default), Fade, or custom CSS effects
Configure auto-play: Set interval and pause behavior
Handle events: Listen to slideChanging and slideChanged for custom logic
Style your carousel: Apply CSS classes and responsive design
Test interactions: Verify touch/keyboard navigation and event handling

See reference files for detailed implementation examples and best practices.

选择数据方案： 静态内容使用items绑定，动态数据使用dataSource
选择导航样式： 按钮、指示器，或两者结合
确定动画效果： 无动画、滑动（默认）、淡入淡出，或自定义CSS效果
配置自动播放： 设置间隔和暂停行为
处理事件： 监听slideChanging和slideChanged事件以执行自定义逻辑
样式化轮播： 应用CSS类和响应式设计
测试交互： 验证触摸/键盘导航和事件处理

有关详细实现示例和最佳实践，请参阅参考文件。