轮播

TuiCarousel 用于在有限空间内循环播放同一类型的图片、文字等内容。 它支持水平/垂直方向滚动，提供极具视觉冲击力的 Card 模式，并且内置了 Motion Blur (动态模糊) 特效，使切换过程更加流畅自然。

基础用法

默认模式 (Default)

最基础的用法。默认情况下，指示器显示在内部，箭头在悬停时显示。

<template>
  <TuiCarousel :height="250">
    <TuiCarouselItem v-for="item in 4" :key="item">
      <div class="demo-content">{{ item }}</div>
    </TuiCarouselItem>
  </TuiCarousel>
</template>

<style scoped>
.demo-content {
  width: 100%;
  height: 100%;
  background-color: var(--primary-base);
  color: white;
  display: flex;
  justify-content: center;
  align-items: center;
  font-size: 24px;
}
</style>

外观模式

卡片模式 (Card)

设置 appearance="card" 即可开启卡片风格。

• cardScale: 控制非激活卡片的缩放比例（默认 0.8）。

<TuiCarousel appearance="card" :cardScale="0.8" :height="250">
  <TuiCarouselItem v-for="item in 6" :key="item">
    </TuiCarouselItem>
</TuiCarousel>

方向与布局

垂直轮播 (Vertical)

设置 direction="v" 即可开启纵向轮播。此时指示器会自动调整位置。

<TuiCarousel direction="v" :height="400">
  </TuiCarousel>

内容与交互

内置标题与描述

TuiCarouselItem 组件不仅仅是一个容器，它内置了遮罩层和文本布局，用于快速展示图文信息。

• title: 标题文本。
• description: 描述文本（支持多行）。
• hasLinkButton: 是否显示跳转按钮（需监听 @navigateTo 事件）。

<script setup>
const handleNavigate = (index) => {
  console.log('Jump to detail:', index);
};
</script>

<template>
  <TuiCarousel :autoplay="false">
    <TuiCarouselItem 
      v-for="(img, index) in images" 
      :key="index"
      title="这里是标题"
      description="这是一段详细的描述文本..."
      :hasLinkButton="true"
      @navigateTo="handleNavigate(index)"
    >
      <img :src="img" style="width:100%; height:100%; object-fit:cover;" />
    </TuiCarouselItem>
  </TuiCarousel>
</template>

动态模糊 (Motion Blur)

组件默认开启了 motionBlur。在快速切换时，会产生运动模糊效果，极大地提升了视觉流畅度和高级感。 如果因性能原因需要关闭，设置 :motionBlur="false" 即可。

指示器与控制器

提供了丰富的属性来定制导航控件：

• indicatorPosition: 指示器位置 (inside, outside, none)。
• indicatorHasIndex: 指示器内是否显示数字序号。
• trigger: 指示器触发方式 (hover, click)。
• arrow: 切换箭头显示策略 (hover, always, never)。

<TuiCarousel 
  indicatorPosition="outside" 
  :indicatorHasIndex="false" 
  arrow="always"
  trigger="click"
>
  ...
</TuiCarousel>

API 参考

TuiCarousel Props

属性名	类型	默认值	说明
height	Number	-	轮播容器高度 (px)。
initialIndex	Number	0	初始激活的索引。
appearance	String	'default'	外观模式。可选：default, card。
direction	String	'h'	轮播方向。可选：h (水平), v (垂直)。
autoplay	Boolean	true	是否自动切换。
interval	Number	3000	自动切换的时间间隔 (ms)。
loop	Boolean	true	是否循环播放。
pauseOnHover	Boolean	true	鼠标悬停时是否暂停自动播放。
trigger	String	'hover'	指示器触发方式。可选：hover, click。
arrow	String	'hover'	切换箭头显示。可选：always, hover, never。
indicatorPosition	String	'inside'	指示器位置。可选：inside, outside, none。
indicatorHasIndex	Boolean	true	指示器是否显示数字索引。
cardScale	Number	0.8	卡片模式下，非激活卡片的缩放比例。
motionBlur	Boolean	true	是否开启切换时的动态模糊特效。
borderRadius	Number	-	容器圆角大小。
sequentialRolling	Boolean	true	是否开启顺序滚动逻辑。
resizeObserver	String	'global'	尺寸监听策略：self, global, none。

TuiCarousel Events

事件名	说明	回调参数
change	幻灯片切换时触发。	(currentIndex, prevIndex)

TuiCarousel Methods (Expose)

方法名	说明	参数
setActiveItem	手动切换到指定索引。	(index: Number)
prev	切换至上一张。	-
next	切换至下一张。	-

TuiCarouselItem Props

属性名	类型	默认值	说明
title	String	-	遮罩层标题。
description	String	-	遮罩层描述文本。
hasLinkButton	Boolean	false	是否显示“详情/跳转”按钮。

TuiCarouselItem Events

事件名	说明	回调参数
navigateTo	点击跳转按钮时触发。	-