Carousel 轮播

用于图片、卡片、营销 Banner、专题推荐等内容轮播。组件支持横向/纵向轮播、卡片模式、露出预览、自适应高度和多种指示器样式。

基础用法

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

const current = ref(0)
const list = [
  'https://img01.yzcdn.cn/vant/cat.jpeg',
  'https://img01.yzcdn.cn/vant/cat.jpeg',
  'https://img01.yzcdn.cn/vant/cat.jpeg',
]
</script>

<template>
  <lk-carousel
    v-model:current="current"
    :carousel-list="list"
  />
</template>

自定义指示器样式

<lk-carousel
  v-model:current="current"
  :carousel-list="list"
  indicator-type="bars"
  indicator-position="top-right"
  indicator-active-color="#fff"
  indicator-inactive-color="rgba(255,255,255,0.4)"
/>

纵向轮播

<lk-carousel
  v-model:current="current"
  :carousel-list="list"
  vertical
  indicator-position="right"
  height="360rpx"
/>

卡片模式

<lk-carousel
  v-model:current="current"
  :carousel-list="list"
  :card="true"
  card-prev-margin="50rpx"
  card-next-margin="50rpx"
  :card-scale="0.9"
  card-radius="24rpx"
  indicator-type="bars"
/>

自定义轮播内容

当 carouselList 中不只是图片地址时，可以配合作用域插槽自定义内容。

<script setup lang="ts">
const cards = [
  { title: '专题一', desc: '新品推荐' },
  { title: '专题二', desc: '限时折扣' },
]
</script>

<template>
  <lk-carousel :carousel-list="cards" :auto-height="true">
    <template #default="{ item, index }">
      <view style="padding: 40rpx; background: #fff; border-radius: 24rpx">
        <view style="font-size: 32rpx; font-weight: 600">{{ index + 1 }}. {{ item.title }}</view>
        <view style="margin-top: 12rpx; color: #666">{{ item.desc }}</view>
      </view>
    </template>
  </lk-carousel>
</template>

自适应高度

<lk-carousel
  :carousel-list="cards"
  :auto-height="true"
  indicator-type="dots"
/>

推荐示例

1) 直接复用项目 Demo（推荐）

<script setup lang="ts">
import CarouselDemo from '@/components/demos/carousel-demo.vue'
</script>

<template>
  <CarouselDemo />
</template>

2) 在业务页中按需组合

<template>
  <view class="page-demo">
    <lk-carousel />
  </view>
</template>

API

Props

参数	说明	类型	默认值
carouselList	轮播数据源	any[]	[]
current	当前激活索引，支持 v-model:current	number	0
autoPlay	是否自动轮播	boolean	true
interval	自动轮播间隔，单位 ms	number	3000
effect	切换效果	fade | slide	fade
vertical	是否纵向轮播	boolean	false
showIndicators	是否显示指示器	boolean	true
indicatorType	指示器类型	dots | bars | number | none	dots
indicatorPosition	指示器位置	bottom | top | left | right | top-left | top-right | bottom-left | bottom-right | auto	auto
indicatorAlign	指示器排列对齐方式	center | start | end	center
indicatorClickable	指示器是否可点击切换	boolean	undefined
indicatorInactiveColor	未激活指示器颜色	string	''
indicatorActiveColor	激活指示器颜色	string	''
card	是否启用卡片模式	boolean	undefined
cardPrevMargin	卡片模式前侧留白	string	''
cardNextMargin	卡片模式后侧留白	string	''
cardScale	非激活卡片缩放比例	number	undefined
cardRadius	卡片圆角	string	''
cardShadow	卡片阴影	string	''
peek	是否启用露出预览模式	boolean	undefined
peekPrevMargin	露出模式前侧留白	string	''
peekNextMargin	露出模式后侧留白	string	''
indicatorAnimated	指示器是否带动画	boolean	undefined
autoHeight	是否根据当前内容自适应高度	boolean	undefined
height	固定高度；关闭自适应时生效	string | number	'320rpx'
indicatorOverlay	指示器是否覆盖在内容上方	boolean	true
loop	是否循环播放	boolean	true
id	根节点 id	string	''
customClass	根节点自定义类名	string | object | array	—
customStyle	根节点自定义样式	string | object	—

Events

事件名	说明	回调参数
update:current	当前索引变化	(index: number)
change	切换时触发	(index, oldIndex, source)
click	点击当前项时触发	(item, index, event)
indicator-click	点击指示器时触发	(index, oldIndex, event)
autoplay-change	自动轮播导致索引变化时触发	(index, oldIndex)
height-change	自适应高度测量变化时触发	(height: number)

Slots

插槽名	说明
default	自定义轮播项内容，作用域参数为 { item, index }

使用建议

TIP

纯图片轮播直接传 carouselList 即可；当每一页是复杂卡片时，推荐使用默认插槽来自定义内容。

发布验收

lk-carousel 已纳入 dynamic-visual showcase 回归，发布前按下面边界验收：

场景	验收方式	要点
展示台基线	自动回归	tests/visual/dynamic-visual-showcase.spec.ts 校验组件路由、verified 状态与中风险标记
动态视觉	自动/人工	fade、slide、卡片模式、指示器位置在截图中保持稳定
平台差异	人工验收	autoplay、纵向轮播、filter/阴影在低端 App WebView 下可接受