3 步配好 Vue3 无缝滚动 Marqueevue3-seamless-scroll 使用与调参【免费下载链接】vue3-seamless-scrollVue3.0 无缝滚动组件项目地址: https://gitcode.com/gh_mirrors/vu/vue3-seamless-scroll公告列表滚到底就生硬跳回顶部循环衔接处还常闪一下。vue3-seamless-scroll 是 Vue3.0 无缝滚动组件基于虚拟列表渲染支持上下左右四个方向的平滑循环滚动。 30 秒跑通先安装npm 与 yarn 任选其一npm install vue3-seamless-scroll yarn add vue3-seamless-scroll入口文件全局注册一次即可三个组件横竖通用、纯竖向、纯横向都会挂上import { createApp } from vue import App from ./App.vue import Vue3SeamlessScroll from vue3-seamless-scroll const app createApp(App) app.use(Vue3SeamlessScroll) app.mount(#app)然后在任意页面里放一段最简调用容器样式见下方template div classbox vue3-seamless-scroll :listlist template #default{ data } div classitem{{ data.title }}/div /template /vue3-seamless-scroll /div /template script setup import { ref } from vue const list ref(Array.from({ length: 20 }, (_, i) ({ title: 公告 ${i 1} }))) /script容器样式只有两行.box { height: 200px; overflow: hidden; }跑起来后容器里的条目会以默认速度向上平滑滚动滚完一圈自动衔接回开头看不到接缝。 能力全景无缝滚动能做什么能力对应配置项一句话说明四方向滚动directionup / down / left / right竖向组件默认 up横向组件默认 left启停动画v-model双向绑定控制暂停与恢复默认开启自动滚动悬停暂停hover鼠标移入即停、移出恢复滚轮驱动wheel悬停时用鼠标滚轮滚动列表依赖 hover 开启单步滚动singleLinesingleWaitTime每滚过一条停顿指定毫秒公告逐条阅读感速度与缓动step/easestep 为每帧像素默认 0.5ease 传 CSS 缓动曲线视口渲染量visibleCount视口内渲染的条数不传则按首条尺寸自动测量数据增删改与分页add/remove/update方法 offset事件ref 暴露数据操作offset 事件作为分页拉取时机默认开启的是自动滚动与视口自动测量hover、wheel、singleLine 均默认关闭需要显式开启。 从基础到进阶三个典型用法基础单方向默认参数前置条件就两条容器固定高度、overflow: hidden。组件挂载时测量容器尺寸数据总高度超过容器才会进入滚动模式否则静止显示。template !-- 容器必须定高并隐藏溢出否则内容会把页面撑开 -- div classscroll-box vertical-scroll :listlist template #default{ data } div classitem{{ data.title }}/div /template /vertical-scroll /div /template script setup import { ref } from vue import { VerticalScroll } from vue3-seamless-scroll // 数据要足够多让总高度超过容器组件才会开始滚动 const list ref(Array.from({ length: 20 }, (_, i) ({ title: 公告 ${i 1} }))) /script样式单独给容器写.scroll-box { height: 200px; overflow: hidden; }交互悬停暂停与滚轮驱动hover 与 wheel 是一对组合滚轮监听只在 hover 开启时生效单独开 wheel 没有效果。另外 direction 只在挂载时读取运行中改 prop 不会转向需要靠 key 重建组件。template !-- :key 绑定方向值切换方向时强制重建保证新方向生效 -- div classscroll-box :keydir vue3-seamless-scroll :listlist :directiondir hover wheel :step1 easeease template #default{ data } div classitem{{ data.title }}/div /template /vue3-seamless-scroll /div /templatestep 从 0.5 提到 1 后速度翻倍想调节奏改 step想调手感改 ease。数据驱动增删改与无限分页组件内部按自身状态维护偏移量直接对 list 做 push/splice 会破坏衔接。增、删、改都走 ref 暴露的方法条目高度不一致时手动传 visibleCount跳过首条自动测量。template div classscroll-box vertical-scroll refscrollRef :listlist offsetonOffset template #default{ data } div classitem{{ data.title }}/div /template /vertical-scroll /div /template逻辑部分放在 setup 中import { ref } from vue import { VerticalScroll } from vue3-seamless-scroll const list ref(initData()) const scrollRef ref(null) // 缓冲数据滚完时触发 offset是拉取下一页的时机 function onOffset() { fetchMore().then((rows) scrollRef.value.add(list.value.length, rows)) // 尾部持续裁掉旧数据内存占用稳定在几百条量级 if (list.value.length 200) scrollRef.value.remove(0, 50) }虚拟渲染意味着 DOM 里始终只有 visibleCount 加少量缓冲项官方示例用一万条数据跑满四个方向也不卡顿。容器尺寸变化如响应式断点后调用scrollRef.value.reset()重测视口。 踩坑清单无缝滚动常见报错与表现异常组件不动如果你看到列表静止大概率是数据总高度没超过容器或容器没有定高。给容器固定高度并隐藏溢出保证数据够溢出。增删后跳动、条目重复如果是直接list.push/splice后出现跳变原因是绕过了组件内部偏移状态。改用 ref 上的add/remove/update。窗口缩放后错位视口尺寸只在挂载时测量一次。尺寸变化结束后调用reset()重算。滚轮没反应wheel 在 hover 未开启时被短路。两个开关一起打开即可。⚖️ 选型参考什么时候用它、什么时候不用适合网站公告、跑马灯条新闻与排行榜循环展示实时监控数据滚动商品 marquee 展示墙大数据量万级不想全量渲染需要悬停暂停、滚轮交互不适合需要原生滚动条浏览长内容列表拖拽排序等复杂交互数据高度小于视口、本就无需滚动 一页速查项内容安装npm install vue3-seamless-scroll注册app.use(Vue3SeamlessScroll)局部可解构三个组件必传参数:listArray方向directionup / down / left / right启停v-modelBoolean默认 true交互开关hover、wheel、singleLine默认全关节奏step0.5、singleWaitTime1000ms、delay、ease渲染量visibleCount缺省时自动测量容器 CSS固定高度 overflow: hidden暴露方法add(index, values)/remove(index, num)/update(index, value)/reset()事件offset缓冲滚动完成用于分页拉取先把容器高度与 overflow 核对一遍再调 step 和 hover 到顺手的节奏数据量大就接上 offset 事件做分页。缓冲区与游标逻辑在 packages/Vue3SeamlessScroll.vue读完那段 animation 循环行为就都明白了。【免费下载链接】vue3-seamless-scrollVue3.0 无缝滚动组件项目地址: https://gitcode.com/gh_mirrors/vu/vue3-seamless-scroll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考