Vue3 无缝滚动组件：vue3-seamless-scroll 完整使用指南

2026-02-06 04:21:34作者：仰钰奇

Vue3-seamless-scroll 是一款专为 Vue3.0 设计的无缝滚动组件，支持 Vite2.0 和服务端打包。该组件能够轻松实现上下左右四个方向的无缝滚动效果，支持单步滚动和复杂图标的无缝滚动，完全兼容 Vue3.0 的所有特性平台。

核心特性

多方向滚动支持：支持上下左右四个方向的滚动
单步滚动功能：可控制单步滚动的高度、宽度和等待时间
鼠标悬停控制：支持鼠标悬停暂停滚动功能
数据监听：实时监听数据变化并自动更新滚动内容
自定义动画：支持贝塞尔曲线动画效果定制
响应式设计：完美适配各种屏幕尺寸

安装方法

npm 安装

npm install vue3-seamless-scroll --save

yarn 安装

yarn add vue3-seamless-scroll

浏览器直接引入

<script src="https://unpkg.com/vue3-seamless-scroll@latest/dist/vue3-seamless-scroll.min.js"></script>

组件配置参数详解

基础配置

list (Array, 必需): 无缝滚动列表数据
v-model (Boolean, 默认true): 控制动画滚动与停止
direction (String, 默认"up"): 滚动方向，可选值 up/down/left/right

高级配置

isWatch (Boolean, 默认true): 开启数据更新监听
hover (Boolean, 默认false): 是否开启鼠标悬停暂停
count (Number, 默认infinite): 动画循环次数
limitScrollNum (Number, 默认5): 开启滚动的最小数据量

单步滚动配置

step (Number): 步进速度
singleHeight (Number, 默认0): 单步运动停止的高度
singleWidth (Number, 默认0): 单步运动停止的宽度
singleWaitTime (Number, 默认1000): 单步停止等待时间(ms)

动画效果配置

delay (Number, 默认0): 动画延时时间
ease (String, 默认"ease-in"): 动画效果，可传入贝塞尔曲线数值
copyNum (Number, 默认1): 拷贝列表次数，用于优化无缝滚动效果

组件注册方式

全局注册

在 main.js 文件中进行全局注册：

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');

局部注册

在单个 .vue 文件中局部注册：

import { defineComponent } from "vue";
import { Vue3SeamlessScroll } from "vue3-seamless-scroll";

export default defineComponent({
  components: {
    Vue3SeamlessScroll
  }
})

完整使用示例

<template>
  <vue3-seamless-scroll 
    :list="list" 
    direction="up" 
    v-model="autoStart"
    class="scroll-container"
  >
    <div class="scroll-item" v-for="(item, index) in list" :key="index">
      <span class="title">{{ item.title }}</span>
      <span class="date">{{ formatDate(item.date) }}</span>
    </div>
  </vue3-seamless-scroll>
</template>

<script>
import { defineComponent, ref } from "vue";
import { Vue3SeamlessScroll } from "vue3-seamless-scroll";

export default defineComponent({
  name: "SeamlessScrollDemo",
  components: {
    Vue3SeamlessScroll
  },
  setup() {
    const autoStart = ref(true);
    const list = ref([
      { title: "Vue3无缝滚动组件展示数据第1条", date: Date.now() },
      { title: "Vue3无缝滚动组件展示数据第2条", date: Date.now() },
      { title: "Vue3无缝滚动组件展示数据第3条", date: Date.now() },
      { title: "Vue3无缝滚动组件展示数据第4条", date: Date.now() },
      { title: "Vue3无缝滚动组件展示数据第5条", date: Date.now() },
      { title: "Vue3无缝滚动组件展示数据第6条", date: Date.now() },
      { title: "Vue3无缝滚动组件展示数据第7条", date: Date.now() },
      { title: "Vue3无缝滚动组件展示数据第8条", date: Date.now() }
    ]);

    const formatDate = (timestamp) => {
      return new Date(timestamp).toLocaleString();
    };

    return { list, autoStart, formatDate };
  }
});
</script>

<style scoped>
.scroll-container {
  height: 300px;
  width: 600px;
  margin: 50px auto;
  overflow: hidden;
  border: 1px solid #e0e0e0;
  border-radius: 8px;
  background-color: #f8f9fa;
}

.scroll-item {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 12px 20px;
  border-bottom: 1px solid #eee;
  transition: background-color 0.3s ease;
}

.scroll-item:hover {
  background-color: #e3f2fd;
}

.title {
  font-weight: 500;
  color: #333;
}

.date {
  font-size: 12px;
  color: #666;
}
</style>