Vue3使用Swiper实现列表内容循环滚动效果如果你跟我一样在Vue3项目里要做的不是那种整屏的图片轮播而是一排卡片自动往左滚滚到末尾无缝接上第一张的列表循环滚动那你大概率会在Swiper的文档里绕上一阵子。这个需求在后台管理系统、数据大屏、运营活动页里太常见了——公告列表自动滚动、商品卡片横向循环、榜单信息轮播。Vue3使用Swiper实现列表内容循环滚动效果这件事看似就是装个依赖写几行配置但真正动手时会碰到版本兼容、loop机制、异步数据刷新、组件销毁等一系列连锁问题。这篇文章把我自己从选型到落地、再到被坑后排查的完整过程写出来给正在做同类需求的朋友一个可以直接抄作业的参考。先说结论如果你用的是Vue3 Vite 组合式API认准Swiper 9以上版本别再用老项目里Swiper 5/6的写法。后面我会具体讲为什么以及每个配置项背后的原理。1. 需求拆解你要的是列表循环不是图片轮播很多人在刚开始做这个需求时会下意识去搜Swiper 图片轮播相关的教程然后照着写一个带分页器的大图轮播——方向就偏了。列表循环滚动和传统轮播有个本质区别轮播是一屏一张核心内容列表滚动是一屏同时展示多条记录然后整体向一个方向持续平移。我接到这个需求时的原始场景是这样的运营要在大屏页面上展示一批最新的商品促销信息每条信息包含商品名、价格、标签不需要用户手动操作只要自动向左循环滚动鼠标移上去能暂停。前端页面上这块区域宽度约1200px计划一屏展示5张卡片每张卡片间距16px卡片高度固定80px。这里有几个关键决策点直接影响后面的实现方式滚动方向横向循环滚动比纵向循环在视觉上更吃布局但大屏场景下横向排列信息密度更优。用direction: horizontal默认就是横向如果你要做纵向公告列表改成direction: vertical即可其他逻辑不变。是否需要交互大屏展示通常不需要用户点击翻页但鼠标悬停暂停是刚需。这涉及autoplay.pauseOnMouseEnter配置。数据来源真实项目里数据一定来自接口这就引出了一个最隐蔽的坑——Swiper初始化时数据是空的等接口返回后它不会自己感知数据变化。这一点我在第4章专门讲。另外要明确一个边界Swiper 适合处理数量可控比如几十条到几百条的列表循环。如果你要滚动的是十几万条日志那应该用虚拟滚动方案Swiper 不是干这个的硬上会卡到你怀疑人生。2. 版本选型Vue3环境下为什么不能随手装个Swiper就开始先说个真事我有个同事从旧项目拷贝了一个swiper.vue组件过来里面用的是this.$refs.mySwiper.swiper.slideTo()这种Vue2 Options API写法放到Vue3项目里直接报错。这还只是API层面的问题更麻烦的是Swiper本身的版本演进。Swiper 的版本线大致是这样的版本Vue支持情况主要变化是否推荐用于Vue3新项目Swiper 5.xVue2类名swiper-container不推荐Swiper 6.x刚引入Vue3 beta支持开始模块化不推荐Swiper 7.x官方支持Vue3引入swiper/vue子路径可以但偏旧Swiper 8.x官方支持Vue3稳定模块树可以用Swiper 9.x官方支持Vue3弃用swiper/react全局注册样式引入方式变化推荐Swiper 10/11官方支持Vue3继续优化Tree Shaking推荐这里有个很多人不知道的细节Swiper 9 开始移除了swiper-bundle.css这种全局样式文件,改成了按模块引入。如果你在Vue3项目里按照老教程写import swiper/css/swiper.css直接找不到文件。Vue3 Vite 项目里正确姿势是// 核心样式必引 import swiper/css // 如果你用了分页器 import swiper/css/pagination // 如果你用了导航按钮 import swiper/css/navigation为什么要强调版本因为Vue3使用Swiper实现列表内容循环滚动效果时新旧版本的组件注册方式和Props传递方式差异巨大。Swiper 7/8 开始官方推荐直接在组件里按需引入模块import { Swiper, SwiperSlide } from swiper/vue import { Autoplay, Pagination, Navigation } from swiper/modules注意这个swiper/modules的路径在老版本里是swiper/core之类的路径写错最常见的报错就是Module not found: Cant resolve swiper/modules。遇到这种错先查Swiper版本而不是去改webpack配置。从长期维护角度看我建议新项目直接npm install swiper拿最新稳定版当前11.x。Swiper 10/11 对Vue3的支持非常成熟Tree Shaking 做得很好最终打包体积反而比老版本小。而且 loop 模式在 9 版本上处理得更稳定这一点直接影响我们的列表循环滚动效果。3. 核心实现从零写一个可复用的ListCarousel组件下面直接给出我在项目里使用的完整组件代码基于 Vue3script setup语法 Swiper 11。这个组件我封装了三层逻辑基础渲染、自动播放、鼠标悬停暂停你可以直接复制到项目里改改就能跑。!-- ListCarousel.vue -- template div classlist-carousel !-- 关键数据没回来之前不渲染Swiper避免loop空转 -- Swiper v-iflist.length 0 classlist-carousel__swiper :modules[Autoplay] :slides-per-viewslidesPerView :space-betweenspaceBetween :looptrue :autoplay{ delay: delay, disableOnInteraction: false, pauseOnMouseEnter: true, stopOnLastSlide: false } :speedspeed swiperonSwiperReady slide-changeonSlideChange SwiperSlide v-for(item, index) in list :keyitem.id || index classlist-carousel__slide div classlist-carousel__card clickonCardClick(item) span classcard-name{{ item.name }}/span span classcard-price{{ item.price }}/span /div /SwiperSlide /Swiper div v-else classlist-carousel__empty暂无数据/div /div /template script setup import { ref } from vue import { Swiper, SwiperSlide } from swiper/vue import { Autoplay } from swiper/modules import swiper/css // props外部控制展示数量、间距、滚动速度 const props defineProps({ list: { type: Array, default: () [] }, slidesPerView: { type: Number, default: 5 }, spaceBetween: { type: Number, default: 16 }, delay: { type: Number, default: 1500 }, speed: { type: Number, default: 1000 } }) const emit defineEmits([cardClick, slideChange]) // 拿到swiper实例后续动态更新会用到 const swiperRef ref(null) const onSwiperReady (swiper) { swiperRef.value swiper } const onSlideChange (swiper) { emit(slideChange, swiper.realIndex) } const onCardClick (item) { emit(cardClick, item) } /script style scoped .list-carousel { width: 100%; overflow: hidden; } .list-carousel__swiper { width: 100%; } .list-carousel__slide { height: 80px; } .list-carousel__card { display: flex; align-items: center; justify-content: space-between; padding: 0 16px; height: 80px; background: #fff; border-radius: 8px; border: 1px solid #eee; cursor: pointer; transition: box-shadow 0.2s; } .list-carousel__card:hover { box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); } .list-carousel__empty { height: 80px; display: flex; align-items: center; justify-content: center; color: #999; border: 1px dashed #ddd; border-radius: 8px; } /style这段代码里最核心的配置是:looptrue和:autoplay。loop决定了滚动到末尾是否无缝接回开头autoplay决定滚动节奏和交互行为。我逐一说明每个配置项为什么这么设。3.1 loop的底层原理Swiper是怎么做到无缝的很多人以为loop: true是滚动到最后一张再跳回第一张其实不对。Swiper的loop模式原理是它会复制首尾的slide在真实列表前后各增加一组克隆节点形成一条首尾相接的环。比如你有10条数据Swiper内部可能渲染成 [克隆的后几个slide, 真实slide 1-10, 克隆的前几个slide]然后在合适的时机切换 index让你看起来永远滚不到头。这里有一个所有新手都会忽略的坑Swiper的loop模式要求slide数量必须大于slidesPerView。如果你一屏显示5个但接口只返回了3条数据loop是转不起来的。官方文档的说法是loop without enough slides will crash——简单说就是会报Swiper loop Error: The number of slides is not enough for loop mode。所以我上面的组件里加了v-iflist.length 0还不够保险严谨一点应该在父组件判断list.length slidesPerView时才启用loop否则关闭loop或者直接展示静态列表。3.2 autoplay配置里的三个隐蔽参数autoplay配置对象里的三个参数我踩过坑才理解透彻disableOnInteraction: false默认值是true含义是用户手动滑动一次后自动播放就永久停止。这对运营大屏来说简直是灾难——某个领导手滑拖了一下列表后面就不自动滚了运维还得刷新页面。改成false之后用户手工操作结束后自动播放会恢复。pauseOnMouseEnter: true鼠标移入容器时暂停。这个在Swiper 7 已经不是autoplay的默认行为必须显式开启。stopOnLastSlide: false配合loop使用确保滚到最后一屏后继续循环而不是停下来。注意这个参数和loop是强关联的如果你loop: false但又设了stopOnLastSlide: true滚动到最后一张就停了。3.3 动态数据更新的两个时机列表数据如果是接口返回的list从空数组变成有值Swiper 会通过Vue的响应式自动渲染出slide。但如果你在同一个Swiper实例上再次更新list比如刷新按钮列表从10条变成20条Swiper不会自动感知必须手动调用实例的update()方法const refreshList (newList) { list.value newList // 等DOM更新后让Swiper重新计算slide宽度和数量 nextTick(() { if (swiperRef.value) { swiperRef.value.update() } }) }如果不调update()Swiper 仍然按照旧的slide数量计算loop克隆节点你很可能看到滚到最后多出来一截空白或者循环一圈少了几条。这个坑我在第四章会详细还原排查过程。4. 踩坑实录异步数据加载导致Swiper进入幽灵滚动状态这个坑我印象太深了必须单独写一章因为它是Vue3使用Swiper实现列表内容循环滚动效果里最高频的问题没有之一。4.1 现象描述我最初的写法是把Swiper直接渲染在页面上不管数据有没有回来Swiper :looptrue ... SwiperSlide v-foritem in state.list :keyitem.id ... /SwiperSlide /Swiper接口延迟了1.5秒返回打开页面时视觉效果是这样的Swiper先渲染了一个空容器等数据回来后slide是出现了但loop的克隆节点数量完全错乱自动播放滚起来偶尔跳帧更离谱的是——明明只有8条数据滚动到某个位置会看到一个完全空白的slide。4.2 排查链路我当时没有直接去网上搜答案而是沿着代码走了一遍排查流程这里把关键路径列出来第一步确认数据是否渲染成slide了。在SwiperSlide内部打印item.name发现每个slide内容都有。第二步检查Swiper实例内部的slide统计。在swiper事件里打印swiper.slides.length。这一步发现了问题接口返回前Swiper初始化完成此时slides.length是一个很小的数字0或1但loop模式下Swiper是根据初始化时的slide数量计算克隆节点的。数据更新后slide数量变化了但克隆节点的数量还是按初识状态来的这就导致循环链条中间出现空洞——那个空白slide就是它。第三步验证是不是响应式更新不及时。尝试在数据更新后手动调swiper.update()调用后空白slide消失循环恢复正常。由此确认问题根源Swiper实例的初始化发生在数据到达之前loop克隆逻辑基于旧的DOM状态。4.3 根因与解决方案根因一句话总结不要在数据未就绪时初始化带loop模式的Swiper。解决方案有三个层级我按推荐程度排序方案A最简单像我在第三节组件里写的那样用v-iflist.length 0控制Swiper的渲染。数据没回来之前干脆不渲染Swiper渲染一个空状态占位。这样Swiper初始化时数据一定是完整的loop克隆也不会乱。方案B应对频繁数据刷新如果列表数据会频繁更新比如websocket推送新榜单不能每次都用v-if销毁重建因为重建会丢失滚动位置和动画状态。这时候要用swiperRef.value.update()swiperRef.value.loopFix()const updateList (newList) { list.value newList nextTick(() { if (swiperRef.value) { swiperRef.value.update() swiperRef.value.loopFix() } }) }方案C治本把Swiper实例的创建也放进nextTick确保它永远在数据渲染完之后初始化。其实方案A已经隐式实现了这一点所以实际项目中首选方案A方案B作为补充。这个坑让我养成了一个习惯凡是Swiper的loop模式必须检查数据生命周期和组件初始化的先后顺序不然调试起来非常消耗时间。5. 进阶需求悬停暂停、切换高亮、以及到底要不要循环的判断基础循环滚动跑通之后真实业务往往会有几个紧接着的进阶需求。我把它们一次说清。5.1 鼠标悬停暂停与恢复如果你直接使用我在第三节提供的pauseOnMouseEnter: true配置在Swiper 11上实测是可以正常工作的。但要注意一个兼容性细节旧版本Swiper 6及以下中pauseOnMouseEnter这个字段写在autoplay外层结构完全不一样。如果你是从网上老教程拷贝的配置一定要检查autoplay是不是一个嵌套对象。另一个相关需求是鼠标移出后立即恢复滚动还是等待当前延迟结束。默认行为是等待delay毫秒结束再恢复如果你希望移出后立即滚动官方没有直接配置项需要在mouseenter/mouseleave事件里手动处理// 在组件中监听 const handleMouseEnter () { if (swiperRef.value) { swiperRef.value.autoplay.stop() } } const handleMouseLeave () { if (swiperRef.value) { swiperRef.value.autoplay.start() } }但这种方式要小心如果在stop()状态下手动start()它不会重置当前延迟计数而是从当前位置继续倒计时。实测下来pauseOnMouseEnter的行为更接近真实需求——暂停时保留位置移出后重新开始一个完整延迟周期。所以绝大多数场景我推荐直接用配置项不用手动事件。5.2 循环滚动中当前项高亮列表循环滚动时运营经常要求当前滚动到中间那张卡片要高亮显示。Swiper里获取当前激活项可以用swiper.realIndex——注意是realIndex而不是activeIndex。因为在loop模式下activeIndex返回的是包含克隆节点在内的索引这个值是跳的不适合拿来做数据对应关系。realIndex才是真实数据项的下标。组件里我通过slide-change事件对外抛出了swiper.realIndex父组件可以这样高亮ListCarousel :listgoodsList slide-changeonSlideChange / div v-for(item, i) in goodsList :class{ active: i currentIndex }高亮样式怎么做如果你只是给卡片加个边框或阴影直接在父组件的循环里比较索引即可。如果你要高亮的位置固定是容器中间的卡片那就要配合centeredSlides: true配置让当前激活项自动居中然后基于realIndex切换样式类。5.3 要不要关闭loop——滚到底就停的业务场景不是所有列表循环都要求无缝回绕。有一种很常见的情况数据有明确的时间顺序比如公告1到公告10产品要求列表从左滚到右滚完最后一屏就静止不再循环回去。这种场景下 loop 反而是错的设计。实现方式很简单:loopfalse并且autoplay.stopOnLastSlide: true。此时Swiper会像一个正常的传送带滚到尽头停下来。但你要注意另一个问题loop: false时首尾没有克隆节点所以第一屏和最后一屏的滑动是卡到边缘的没有那种回弹效果。如果你希望最后一屏停得自然一点可以给container加overscroll-behavior或者设置足够的spaceBetween来缓冲。我的判断标准是这样的业务场景是否开启loop原因大屏数据看板运营信息循环开启需要长时间无人值守自动滚动公告列表按时间倒序轮播关闭数据有顺序滚完即止更合理商品推荐位循环展示开启无明确首尾逻辑需要无缝感带用户手动翻页的列表通常关闭用户可控优先避免loop导致翻不到尽头6. 封装与性能这个组件还能怎么扩展第三节给出的组件已经能跑通基本需求但在真实项目里你可能还要考虑这些事。6.1 用slot扩展卡片内容我在组件里硬编码了item.name和item.price的渲染但真实业务里卡片内容五花八门——可能是带图的商品卡片可能是带状态的工单列表甚至可能是实时变动的比分板。更好的设计是用slot把slide的内容交给父组件定制SwiperSlide v-for(item, index) in list :keygetKey(item, index) slot :itemitem :indexindex !-- 默认渲染如果父组件不传slot就显示这段 -- div classlist-carousel__card{{ item.name }}/div /slot /SwiperSlide父组件使用时ListCarousel :listlist template #default{ item, index } div classcustom-card img :srcitem.pic / p{{ item.title }}/p /div /template /ListCarousel注意loop模式下Swiper渲染的slide包含克隆节点但是克隆节点不会重新触发插槽渲染逻辑——Swiper的克隆是直接复制DOM所以事件绑定和插槽内容都会被原样克隆。这句话的意思是在插槽模板里绑定的事件克隆节点上一样会触发不需要做额外处理。但反过来说如果插槽模板依赖了某个只能在Vue渲染期间才能生成的DOM状态比如随机数那么克隆节点会复制第一次渲染的结果而不是重新生成——这块需要注意。6.2 大数据量会卡先确认你的瓶颈在哪当列表数据超过200条时Swiper默认会把所有slide渲染到DOM上尤其在loop模式下还会追加克隆节点这可能导致首屏渲染变慢甚至卡顿。但这个卡顿要分情况数据量大但每次可见的只有5个瓶颈不是Swiper的计算而是200个slide全部挂在DOM上带来的内存占用和样式计算。解决方案有两个一是只渲染一部分slide显然违背了循环滚动全部数据的需求二是用Swiper 11提供的virtual模块虚拟滑动它只根据当前索引动态渲染可视区域的slide。// 启用virtual模块 import { Virtual } from swiper/modules Swiper :modules[Autoplay, Virtual] :virtualtrue 但这里我要泼一盆冷水loop 和 virtual 同时开启在部分Swiper版本上有兼容性问题尤其是update()动态更新数据时虚拟列表容易错位。我在调研阶段测试过 Swiper 10/11Swiper 10 上 loopvirtual 偶发空白slideSwiper 11 上稳定性好一些但也不敢说100%没问题。所以在真实项目中如果业务数据量在200条以内我会放弃virtual直接用全量渲染——简单可靠才是首要的如果数据量过千就不该用Swiper做列表循环了应该重新评估产品方案。6.3 组件销毁时必须释放Swiper实例Vue 3中组件卸载后Swiper实例如果不手动销毁会残留一些全局事件监听尤其是autoplay定时器和resize监听。表现在页面上就是路由切换到别的页面控制台还会偶尔报Cannot read properties of undefined之类错误。在script setup里这样处理import { onBeforeUnmount } from vue onBeforeUnmount(() { if (swiperRef.value) { swiperRef.value.destroy(true, true) swiperRef.value null } })destroy()的两个参数第一个deleteInstance是彻底删除实例第二个cleanStyles是清除Swiper在DOM上留下的内联样式。建议都传true不然切换路由再回来时你会发现容器宽度不是100%了而是上一次初始化时设置的固定像素值——这个坑很隐蔽不查半天根本想不到是上次实例没清理干净。6.4 响应式断点不同屏幕宽度展示不同卡片数大屏项目里同一个组件可能要适配不同分辨率。Swiper 的breakpoints配置项就是干这个的const breakpoints { 320: { slidesPerView: 2, spaceBetween: 10 }, 768: { slidesPerView: 3, spaceBetween: 16 }, 1200: { slidesPerView: 5, spaceBetween: 20 } }在组件里直接:breakpointsbreakpoints即可。注意breakpoints的断点值是最小宽度也就是说屏幕宽度≥1200px时用5张卡片≥768px时用3张依次向下匹配。如果你的容器宽度不是全屏而是某个固定区域比如center布局下只有1000px宽那么断点应该以容器宽度为准这时不能直接用breakpoints需要借助ResizeObserver监听容器宽度然后动态设置slidesPerView。7. 实际项目中的避坑补充与优化建议7.1 卡片高度不一致会导致滚动错位Swiper默认slidesPerView是多列布局如果每张卡片高度不一样列表会出现参差不齐的边缘。团队里如果UI稿规定了固定高度那没问题但如果卡片内容是动态的文字有长有短强烈建议打开这个配置:auto-heightfalse等等Swiper根本没有全局autoHeight用在多列场景的选项。Swiper的autoHeight只会作用于整个容器不是每列单独自适应。多列布局下正确的做法是给每个slide内部设置height: 100%然后让卡片内容自己撑开或者固定高度。我在项目里的经验是——不要让Swiper去猜高度直接把slide和card的高度写死这是最省心的方案。7.2 使用slidesPerGroup控制每次滚动步长默认情况下autoplay每次滚动一格也就是一张卡片。如果你想让它每次滚动一屏比如每次移动5张卡片的距离需要设置slidesPerGroup: 5。这个参数在运营配置里很常见比如设计稿要求每3秒切换一整屏共5屏展示25条数据。但要注意slidesPerGroup配合 loop 模式时Swiper需要确保slide总数能被slidesPerGroup整除否则滚到最后会多出一个不完整的残屏。如果数据不能被整除Swiper 的loop会自动调整但偶尔会出现最后一步跳两格的动画异常。解决方案有两个一是数据够多时截断list的前N条来凑整除二是干脆用slidesPerGroup: 1每次滚动一格这其实是更多大屏项目的选择——滚动节奏更细腻不会一屏一屏地跳。7.3 需要手动控制滚动方向怎么办运营有时候想按住按钮手动往前翻不想等自动播放。Swiper实例暴露了slideNext()和slidePrev()方法const handlePrev () { if (swiperRef.value) { swiperRef.value.slidePrev() } } const handleNext () { if (swiperRef.value) { swiperRef.value.slideNext() } }在loop模式下这两个方法都会自动处理克隆节点不用担心滚到边界卡住。手动翻页时如果想临时停止自动播放在按钮事件里先swiper.autoplay.stop()等用户停止操作3秒后再start()。这样交互上更友好不会出现用户正在看列表又开始自动滚的焦虑感。7.4 性能优化的最后一招减少重渲染真实项目里list数据如果是接口返回的每次刷新后整个组件v-for的slide都会重新创建。如果卡片内部还有图片会造成大量图片重新加载严重时卡片闪烁。这时候用Vue自带的关键东西——key一定要绑定稳定的唯一id而不是index。用index做key的坏处是当list头部插入新数据时所有卡片更新但内容错位。更麻烦的是Swiper的克隆节点配合index key可能在loop时出现两个slide内容相同但key不同的混乱。正确的key规则优先用item.id没有id就用index拼接一个前缀如slide-${index}但要做到列表数据顺序固定时key不变。如果你用websocket推送新数据插到头部key应该用后端生成的消息id否则每次推送都会导致整列重新渲染。至此从需求拆解、版本选型、核心组件实现、异步数据的坑、进阶交互到性能优化这个Vue3使用Swiper实现列表内容循环滚动效果的完整链路已经拉通了。这套代码和排查思路在我的项目里经过了实际生产环境验证你在参考时如果遇到我文中提到的报错信息大概率能直接定位到问题。最后提醒一句如果接口可能失败或返回空数据记得处理空状态展示否则loop报错不是报错而是一段完全空白的不动容器看起来像页面挂了一样。