在前端开发中，轮播（Slideshow/Carousel）是最常见的UI组件之一，无论是官网首页、商品展示还是内容推荐，都能看到它的身影。市面上虽然有很多现成的轮播组件库，但要么体积过大，要么定制性不足。今天我将分享一个自己实现的、基于Vue3 + TypeScript的轻量级轮播组件，它功能完备、易于扩展，且完全符合Vue3的组合式API最佳实践。

组件特性

这个轮播组件具备了生产环境所需的核心功能，同时保持了轻量和可定制性：

• ✅ 支持多种动画效果：滑动（slide）、淡入淡出（fade）、缩放（zoom）、翻转（flip）、立方体（cube）
• ✅ 支持水平/垂直两种轮播方向
• ✅ 自动播放 + 鼠标悬停暂停
• ✅ 触摸滑动（移动端）+ 鼠标拖拽（PC端）
• ✅ 自定义指示器位置（上/下/左/右）
• ✅ 箭头导航 + 循环/非循环模式
• ✅ 丰富的自定义插槽和事件回调
• ✅ 完整的TypeScript类型定义
• ✅ 响应式适配，适配移动端和PC端

快速上手

1. 组件引入

将上面的代码保存为 LucasSlideshow.vue 文件，然后在你的Vue3项目中直接引入使用：

2. 基础使用示例

这是最简化的使用方式，只需要传入轮播数据即可：

<template>
  <LucasSlideshow :slides="slides" />
</template>

<script setup lang="ts">
import LucasSlideshow from './LucasSlideshow.vue'

// 轮播数据（符合SlideItem接口）
const slides = [
  {
    src: '/images/slide1.jpg',
    alt: '第一张轮播图',
    title: '夏日新品上市',
    link: '/products/summer'
  },
  {
    src: '/images/slide2.jpg',
    alt: '第二张轮播图',
    title: '限时优惠活动',
    link: '/promotion',
    target: '_blank'
  },
  {
    src: '/images/slide3.jpg',
    alt: '第三张轮播图',
    title: '会员专享福利',
    link: '/vip'
  }
]
</script>

3. 自定义配置示例

如果你需要定制轮播的样式和行为，可以传入更多配置项：

<template>
  <LucasSlideshow
    :slides="slides"
    width="800px"
    height="450px"
    animation="zoom"
    direction="horizontal"
    :interval="4000"
    :loop="true"
    indicator-position="top"
    @change="handleSlideChange"
    @click="handleSlideClick"
  >
    <!-- 自定义轮播内容插槽 -->
    <template #slide="{ slide, active }">
      <div v-if="active" class="slide-title">{{ slide.title }}</div>
    </template>

    <!-- 自定义控制区插槽 -->
    <template #controls="{ current, total, prev, next }">
      <div class="custom-controls">
        {{ current + 1 }} / {{ total }}
        <button @click="prev">上一页</button>
        <button @click="next">下一页</button>
      </div>
    </template>
  </LucasSlideshow>
</template>

<script setup lang="ts">
import LucasSlideshow from './LucasSlideshow.vue'

const slides = [/* 轮播数据 */]

// 轮播切换事件
const handleSlideChange = (index: number, slide: any) => {
  console.log('当前轮播索引：', index, '当前轮播项：', slide)
}

// 轮播点击事件
const handleSlideClick = (index: number, slide: any, event: MouseEvent) => {
  console.log('点击了第', index + 1, '张轮播图')
}
</script>

<style scoped>
.slide-title {
  position: absolute;
  bottom: 20px;
  left: 20px;
  color: white;
  font-size: 20px;
  text-shadow: 0 2px 4px rgba(0,0,0,0.5);
}

.custom-controls {
  position: absolute;
  top: 10px;
  right: 20px;
  color: white;
  display: flex;
  align-items: center;
  gap: 10px;
}

.custom-controls button {
  padding: 4px 8px;
  border: none;
  border-radius: 4px;
  background: rgba(0,0,0,0.5);
  color: white;
  cursor: pointer;
}
</style>

完整API列表

1. SlideItem 接口（轮播项类型）

2. Props（组件属性）

3. Events（组件事件）

4. Slots（插槽）

5. Exposed Methods（暴露的方法）

可以通过模板引用（ref）调用这些方法：

<template>
  <LucasSlideshow ref="slideshowRef" :slides="slides" />
  <button @click="handleGoTo(2)">跳转到第三张</button>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import LucasSlideshow from './LucasSlideshow.vue'

const slideshowRef = ref<InstanceType<typeof LucasSlideshow>>()

const handleGoTo = (index: number) => {
  slideshowRef.value?.goTo(index)
}
</script>

样式定制

组件的样式使用了scoped样式，且所有class都带有lucas-slideshow__前缀，你可以通过深度选择器（::v-deep / :deep()）来覆盖默认样式：

<style scoped>
:deep(.lucas-slideshow__arrow) {
  background: rgba(0, 0, 0, 0.5);
  color: white;
}

:deep(.lucas-slideshow__indicator--active) {
  background: #ff4400;
}
</style>

总结

这个Vue3+TS轮播组件具备了生产环境所需的核心功能，同时保持了良好的可定制性和类型安全性。核心亮点总结：

1. 功能完备：支持多种动画、触摸/拖拽、自动播放等核心功能，满足大部分业务场景；
2. 类型安全：基于TypeScript开发，提供完整的接口定义，减少使用时的类型错误；
3. 易于扩展：通过插槽和暴露的方法，可灵活定制轮播的外观和行为；
4. 体验友好：支持响应式适配，鼠标悬停暂停、拖拽阈值等细节优化提升用户体验。

你可以直接将这个组件集成到你的Vue3项目中，也可以根据自己的业务需求进一步扩展（比如添加懒加载、缩略图导航等功能）。希望这个组件能帮助到你！

源码

<script setup lang="ts">
import { ref, computed, onMounted, onUnmounted, watch } from 'vue'

// 幻灯片项接口
export interface SlideItem {
  id?: string | number
  src: string
  alt?: string
  title?: string
  link?: string
  target?: '_blank' | '_self'
}

// Props 定义
interface Props {
  slides: SlideItem[]
  width?: string | number
  height?: string | number
  autoplay?: boolean
  interval?: number
  animation?: 'fade' | 'slide' | 'zoom' | 'flip' | 'cube'
  direction?: 'horizontal' | 'vertical'
  objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'
  showIndicators?: boolean
  showArrows?: boolean
  indicatorPosition?: 'bottom' | 'top' | 'left' | 'right'
  loop?: boolean
  pauseOnHover?: boolean
  touchable?: boolean
  draggable?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  width: '100%',
  height: '300px',
  autoplay: true,
  interval: 3000,
  animation: 'slide',
  direction: 'horizontal',
  objectFit: 'cover',
  showIndicators: true,
  showArrows: true,
  indicatorPosition: 'bottom',
  loop: true,
  pauseOnHover: true,
  touchable: true,
  draggable: true
})

const emit = defineEmits<{
  'change': [index: number, slide: SlideItem]
  'click': [index: number, slide: SlideItem, event: MouseEvent]
}>()

// 状态
const currentIndex = ref(0)
const isAnimating = ref(false)
const isPaused = ref(false)
const containerRef = ref<HTMLElement | null>(null)

// 触摸/拖拽状态
const touchStartX = ref(0)
const touchStartY = ref(0)
const touchDeltaX = ref(0)
const touchDeltaY = ref(0)
const isDragging = ref(false)

// 自动播放定时器
let autoplayTimer: ReturnType<typeof setInterval> | null = null

// 计算样式
const containerStyle = computed(() => ({
  width: typeof props.width === 'number' ? `${props.width}px` : props.width,
  height: typeof props.height === 'number' ? `${props.height}px` : props.height
}))

// 幻灯片轨道样式
const trackStyle = computed(() => {
  if (props.animation === 'slide') {
    const offset = props.direction === 'horizontal'
      ? `translateX(calc(-${currentIndex.value * 100}% + ${isDragging.value ? touchDeltaX.value : 0}px))`
      : `translateY(calc(-${currentIndex.value * 100}% + ${isDragging.value ? touchDeltaY.value : 0}px))`
    return {
      transform: offset,
      transition: isDragging.value ? 'none' : 'transform 0.5s ease'
    }
  }
  return {}
})

// 获取幻灯片类名
const getSlideClass = (index: number) => {
  const classes = ['lucas-slideshow__slide']
  if (index === currentIndex.value) classes.push('lucas-slideshow__slide--active')
  if (index === currentIndex.value - 1 || (currentIndex.value === 0 && index === props.slides.length - 1)) {
    classes.push('lucas-slideshow__slide--prev')
  }
  if (index === currentIndex.value + 1 || (currentIndex.value === props.slides.length - 1 && index === 0)) {
    classes.push('lucas-slideshow__slide--next')
  }
  return classes
}

// 切换到指定索引
const goTo = (index: number) => {
  if (isAnimating.value || props.slides.length === 0) return

  let targetIndex = index
  if (props.loop) {
    if (index < 0) targetIndex = props.slides.length - 1
    else if (index >= props.slides.length) targetIndex = 0
  } else {
    if (index < 0) targetIndex = 0
    else if (index >= props.slides.length) targetIndex = props.slides.length - 1
  }

  if (targetIndex === currentIndex.value) return

  isAnimating.value = true
  currentIndex.value = targetIndex
  emit('change', targetIndex, props.slides[targetIndex]!)

  setTimeout(() => {
    isAnimating.value = false
  }, 500)
}

// 上一张/下一张
const prev = () => goTo(currentIndex.value - 1)
const next = () => goTo(currentIndex.value + 1)

// 点击事件处理
const handleSlideClick = (index: number, slide: SlideItem, event: MouseEvent) => {
  emit('click', index, slide, event)
  if (slide.link) {
    if (slide.target === '_blank') {
      window.open(slide.link, '_blank')
    } else {
      window.location.href = slide.link
    }
  }
}

// 触摸事件处理
const handleTouchStart = (e: TouchEvent) => {
  if (!props.touchable) return
  const touch = e.touches[0]!
  touchStartX.value = touch.clientX
  touchStartY.value = touch.clientY
  touchDeltaX.value = 0
  touchDeltaY.value = 0
  isDragging.value = true
  stopAutoplay()
}

const handleTouchMove = (e: TouchEvent) => {
  if (!isDragging.value || !props.touchable) return
  const touch = e.touches[0]!
  touchDeltaX.value = touch.clientX - touchStartX.value
  touchDeltaY.value = touch.clientY - touchStartY.value

  // 阻止页面滚动（当水平滑动时）
  if (props.direction === 'horizontal' && Math.abs(touchDeltaX.value) > Math.abs(touchDeltaY.value)) {
    e.preventDefault()
  }
}

const handleTouchEnd = () => {
  if (!isDragging.value) return
  isDragging.value = false

  const threshold = 50
  const delta = props.direction === 'horizontal' ? touchDeltaX.value : touchDeltaY.value

  if (Math.abs(delta) > threshold) {
    if (delta > 0) prev()
    else next()
  }

  touchDeltaX.value = 0
  touchDeltaY.value = 0
  startAutoplay()
}

// 鼠标拖拽事件处理
const handleMouseDown = (e: MouseEvent) => {
  if (!props.draggable) return
  e.preventDefault()
  touchStartX.value = e.clientX
  touchStartY.value = e.clientY
  touchDeltaX.value = 0
  touchDeltaY.value = 0
  isDragging.value = true
  stopAutoplay()

  document.addEventListener('mousemove', handleMouseMove)
  document.addEventListener('mouseup', handleMouseUp)
}

const handleMouseMove = (e: MouseEvent) => {
  if (!isDragging.value) return
  touchDeltaX.value = e.clientX - touchStartX.value
  touchDeltaY.value = e.clientY - touchStartY.value
}

const handleMouseUp = () => {
  if (!isDragging.value) return
  isDragging.value = false

  const threshold = 50
  const delta = props.direction === 'horizontal' ? touchDeltaX.value : touchDeltaY.value

  if (Math.abs(delta) > threshold) {
    if (delta > 0) prev()
    else next()
  }

  touchDeltaX.value = 0
  touchDeltaY.value = 0
  startAutoplay()

  document.removeEventListener('mousemove', handleMouseMove)
  document.removeEventListener('mouseup', handleMouseUp)
}

// 自动播放控制
const startAutoplay = () => {
  if (!props.autoplay || isPaused.value) return
  stopAutoplay()
  autoplayTimer = setInterval(() => {
    next()
  }, props.interval)
}

const stopAutoplay = () => {
  if (autoplayTimer) {
    clearInterval(autoplayTimer)
    autoplayTimer = null
  }
}

// 鼠标悬停暂停
const handleMouseEnter = () => {
  if (props.pauseOnHover) {
    isPaused.value = true
    stopAutoplay()
  }
}

const handleMouseLeave = () => {
  if (props.pauseOnHover) {
    isPaused.value = false
    startAutoplay()
  }
}

// 暴露方法
defineExpose({
  goTo,
  prev,
  next,
  currentIndex: computed(() => currentIndex.value)
})

// 监听 slides 变化
watch(() => props.slides, () => {
  if (currentIndex.value >= props.slides.length) {
    currentIndex.value = Math.max(0, props.slides.length - 1)
  }
}, { deep: true })

// 生命周期
onMounted(() => {
  startAutoplay()
})

onUnmounted(() => {
  stopAutoplay()
  document.removeEventListener('mousemove', handleMouseMove)
  document.removeEventListener('mouseup', handleMouseUp)
})
</script>

<template>
  <div
    ref="containerRef"
    class="lucas-slideshow"
    :class="[
      `lucas-slideshow--${props.animation}`,
      `lucas-slideshow--${props.direction}`,
      `lucas-slideshow--indicators-${props.indicatorPosition}`
    ]"
    :style="containerStyle"
    @mouseenter="handleMouseEnter"
    @mouseleave="handleMouseLeave"
  >
    <!-- 幻灯片轨道 -->
    <div
      class="lucas-slideshow__track"
      :style="trackStyle"
      @touchstart="handleTouchStart"
      @touchmove="handleTouchMove"
      @touchend="handleTouchEnd"
      @mousedown="handleMouseDown"
    >
      <div
        v-for="(slide, index) in props.slides"
        :key="slide.id ?? index"
        :class="getSlideClass(index)"
        @click="handleSlideClick(index, slide, $event)"
      >
        <img
          :src="slide.src"
          :alt="slide.alt || `Slide ${index + 1}`"
          class="lucas-slideshow__image"
          :style="{ objectFit: props.objectFit }"
          draggable="false"
        />
        <!-- 自定义内容插槽 -->
        <slot name="slide" :slide="slide" :index="index" :active="index === currentIndex"></slot>
      </div>
    </div>

    <!-- 左右箭头 -->
    <template v-if="props.showArrows && props.slides.length > 1">
      <button
        class="lucas-slideshow__arrow lucas-slideshow__arrow--prev"
        @click.stop="prev"
        :disabled="!props.loop && currentIndex === 0"
      >
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
          <polyline points="15 18 9 12 15 6"></polyline>
        </svg>
      </button>
      <button
        class="lucas-slideshow__arrow lucas-slideshow__arrow--next"
        @click.stop="next"
        :disabled="!props.loop && currentIndex === props.slides.length - 1"
      >
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
          <polyline points="9 18 15 12 9 6"></polyline>
        </svg>
      </button>
    </template>

    <!-- 指示器 -->
    <div v-if="props.showIndicators && props.slides.length > 1" class="lucas-slideshow__indicators">
      <button
        v-for="(_, index) in props.slides"
        :key="index"
        class="lucas-slideshow__indicator"
        :class="{ 'lucas-slideshow__indicator--active': index === currentIndex }"
        @click.stop="goTo(index)"
      ></button>
    </div>

    <!-- 自定义控制区插槽 -->
    <slot name="controls" :current="currentIndex" :total="props.slides.length" :prev="prev" :next="next" :goTo="goTo"></slot>
  </div>
</template>

<style scoped>
.lucas-slideshow {
  position: relative;
  overflow: hidden;
  background: #000;
  user-select: none;
}

/* 轨道样式 */
.lucas-slideshow__track {
  display: flex;
  width: 100%;
  height: 100%;
}

.lucas-slideshow--vertical .lucas-slideshow__track {
  flex-direction: column;
}

/* 幻灯片样式 */
.lucas-slideshow__slide {
  flex-shrink: 0;
  width: 100%;
  height: 100%;
  position: relative;
  cursor: pointer;
}

.lucas-slideshow__image {
  width: 100%;
  height: 100%;
  display: block;
}

/* Fade 动画 */
.lucas-slideshow--fade .lucas-slideshow__track {
  display: block;
}

.lucas-slideshow--fade .lucas-slideshow__slide {
  position: absolute;
  top: 0;
  left: 0;
  opacity: 0;
  transition: opacity 0.5s ease;
  pointer-events: none;
}

.lucas-slideshow--fade .lucas-slideshow__slide--active {
  opacity: 1;
  pointer-events: auto;
  z-index: 1;
}

/* Zoom 动画 */
.lucas-slideshow--zoom .lucas-slideshow__track {
  display: block;
}

.lucas-slideshow--zoom .lucas-slideshow__slide {
  position: absolute;
  top: 0;
  left: 0;
  opacity: 0;
  transform: scale(0.8);
  transition: opacity 0.5s ease, transform 0.5s ease;
  pointer-events: none;
}

.lucas-slideshow--zoom .lucas-slideshow__slide--active {
  opacity: 1;
  transform: scale(1);
  pointer-events: auto;
  z-index: 1;
}

/* Flip 动画 */
.lucas-slideshow--flip {
  perspective: 1000px;
}

.lucas-slideshow--flip .lucas-slideshow__track {
  display: block;
  transform-style: preserve-3d;
}

.lucas-slideshow--flip .lucas-slideshow__slide {
  position: absolute;
  top: 0;
  left: 0;
  opacity: 0;
  transform: rotateY(90deg);
  transition: opacity 0.5s ease, transform 0.5s ease;
  backface-visibility: hidden;
  pointer-events: none;
}

.lucas-slideshow--flip .lucas-slideshow__slide--active {
  opacity: 1;
  transform: rotateY(0deg);
  pointer-events: auto;
  z-index: 1;
}

.lucas-slideshow--flip .lucas-slideshow__slide--prev {
  transform: rotateY(-90deg);
}

.lucas-slideshow--flip .lucas-slideshow__slide--next {
  transform: rotateY(90deg);
}

/* Cube 动画 */
.lucas-slideshow--cube {
  perspective: 1000px;
}

.lucas-slideshow--cube .lucas-slideshow__track {
  display: block;
  transform-style: preserve-3d;
  transition: transform 0.6s ease;
}

.lucas-slideshow--cube .lucas-slideshow__slide {
  position: absolute;
  top: 0;
  left: 0;
  opacity: 0;
  transform: translateZ(-150px) rotateY(90deg);
  transition: opacity 0.5s ease, transform 0.5s ease;
  backface-visibility: hidden;
  pointer-events: none;
}

.lucas-slideshow--cube .lucas-slideshow__slide--active {
  opacity: 1;
  transform: translateZ(0) rotateY(0deg);
  pointer-events: auto;
  z-index: 1;
}

/* 箭头样式 */
.lucas-slideshow__arrow {
  position: absolute;
  top: 50%;
  transform: translateY(-50%);
  z-index: 10;
  width: 40px;
  height: 40px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: rgba(255, 255, 255, 0.9);
  border: none;
  border-radius: 50%;
  cursor: pointer;
  opacity: 0;
  transition: opacity 0.3s, background 0.2s, transform 0.2s;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
}

.lucas-slideshow:hover .lucas-slideshow__arrow {
  opacity: 1;
}

.lucas-slideshow__arrow:hover {
  background: #fff;
  transform: translateY(-50%) scale(1.1);
}

.lucas-slideshow__arrow:disabled {
  opacity: 0.3;
  cursor: not-allowed;
}

.lucas-slideshow__arrow--prev {
  left: 16px;
}

.lucas-slideshow__arrow--next {
  right: 16px;
}

.lucas-slideshow__arrow svg {
  width: 20px;
  height: 20px;
  color: #333;
}

/* 垂直方向箭头 */
.lucas-slideshow--vertical .lucas-slideshow__arrow {
  left: 50%;
  transform: translateX(-50%);
}

.lucas-slideshow--vertical .lucas-slideshow__arrow--prev {
  top: 16px;
  bottom: auto;
}

.lucas-slideshow--vertical .lucas-slideshow__arrow--next {
  top: auto;
  bottom: 16px;
}

.lucas-slideshow--vertical .lucas-slideshow__arrow--prev svg {
  transform: rotate(90deg);
}

.lucas-slideshow--vertical .lucas-slideshow__arrow--next svg {
  transform: rotate(90deg);
}

.lucas-slideshow--vertical .lucas-slideshow__arrow:hover {
  transform: translateX(-50%) scale(1.1);
}

/* 指示器样式 */
.lucas-slideshow__indicators {
  position: absolute;
  z-index: 10;
  display: flex;
  gap: 8px;
}

/* 指示器位置 */
.lucas-slideshow--indicators-bottom .lucas-slideshow__indicators {
  bottom: 16px;
  left: 50%;
  transform: translateX(-50%);
  flex-direction: row;
}

.lucas-slideshow--indicators-top .lucas-slideshow__indicators {
  top: 16px;
  left: 50%;
  transform: translateX(-50%);
  flex-direction: row;
}

.lucas-slideshow--indicators-left .lucas-slideshow__indicators {
  left: 16px;
  top: 50%;
  transform: translateY(-50%);
  flex-direction: column;
}

.lucas-slideshow--indicators-right .lucas-slideshow__indicators {
  right: 16px;
  top: 50%;
  transform: translateY(-50%);
  flex-direction: column;
}

.lucas-slideshow__indicator {
  width: 8px;
  height: 8px;
  padding: 0;
  border: none;
  border-radius: 50%;
  background: rgba(255, 255, 255, 0.5);
  cursor: pointer;
  transition: all 0.3s;
}

.lucas-slideshow__indicator:hover {
  background: rgba(255, 255, 255, 0.8);
}

.lucas-slideshow__indicator--active {
  background: #fff;
  transform: scale(1.2);
}

/* 左右指示器样式调整 */
.lucas-slideshow--indicators-left .lucas-slideshow__indicator,
.lucas-slideshow--indicators-right .lucas-slideshow__indicator {
  width: 8px;
  height: 8px;
}

/* 响应式 */
@media (max-width: 768px) {
  .lucas-slideshow__arrow {
    width: 32px;
    height: 32px;
    opacity: 0.7;
  }

  .lucas-slideshow__arrow svg {
    width: 16px;
    height: 16px;
  }

  .lucas-slideshow__arrow--prev {
    left: 8px;
  }

  .lucas-slideshow__arrow--next {
    right: 8px;
  }

  .lucas-slideshow__indicators {
    gap: 6px;
  }

  .lucas-slideshow__indicator {
    width: 6px;
    height: 6px;
  }
}
</style>