v3-scroll-list

一个轻量级的Vue 3无缝滚动列表组件库，支持自动滚动、无缝循环、鼠标悬停暂停等功能。

功能特性

• ✨ 无缝滚动循环
• 🎯 可配置滚动速度和步长
• 🖱️ 支持鼠标滚轮控制
• 📦 鼠标悬停自动暂停
• 🎨 支持隐藏滚动条
• 📦 轻量级，无依赖
• 🔌 支持Vue 3插件方式安装

安装

NPM安装

npm install v3-scroll-list

CDN引入

<script src="https://cdn.jsdelivr.net/npm/v3-scroll-list/dist/v3-scroll-list.umd.cjs"></script>

使用方法

方式一：直接使用函数

import { scrollList } from 'v3-scroll-list'

// 获取滚动容器元素
const scrollContainer = document.querySelector('.scroll-container')

// 调用scrollList函数
scrollList({
  el: scrollContainer,
  step: 1,              // 滚动步长
  speed: 30,            // 滚动速度(ms)
  isSeamless: true,     // 开启无缝滚动
  isMouseWheel: true,   // 开启鼠标滚动
  hideScrollbarWidth: false // 隐藏滚动条
})

方式二：Vue 3插件方式

import { createApp } from 'vue'
import App from './App.vue'
import V3ScrollList from 'v3-scroll-list'

const app = createApp(App)
app.use(V3ScrollList)
app.mount('#app')

在组件中使用（Composition API）：

<template>
  <div ref="scrollContainer" class="scroll-container">
    <div class="scroll-item">项目 1</div>
    <div class="scroll-item">项目 2</div>
    <div class="scroll-item">项目 3</div>
    <div class="scroll-item">项目 4</div>
    <div class="scroll-item">项目 5</div>
  </div>
</template>

<script setup>
import { ref, onMounted, getCurrentInstance } from 'vue'

const scrollContainer = ref(null)
const { proxy } = getCurrentInstance()

onMounted(() => {
  proxy.$scrollList({
    el: scrollContainer.value,
    step: 1,
    speed: 30,
    isSeamless: true,
    isMouseWheel: true,
    hideScrollbarWidth: false
  })
})
</script>

<style>
.scroll-container {
  height: 300px;
  overflow: hidden;
}

.scroll-item {
  height: 50px;
  line-height: 50px;
  border-bottom: 1px solid #eee;
}
</style>

或者直接导入使用（推荐）：

<template>
  <div ref="scrollContainer" class="scroll-container">
    <div class="scroll-item">项目 1</div>
    <div class="scroll-item">项目 2</div>
    <div class="scroll-item">项目 3</div>
    <div class="scroll-item">项目 4</div>
    <div class="scroll-item">项目 5</div>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { scrollList } from 'v3-scroll-list'

const scrollContainer = ref(null)

onMounted(() => {
  scrollList({
    el: scrollContainer.value,
    step: 1,
    speed: 30,
    isSeamless: true,
    isMouseWheel: true,
    hideScrollbarWidth: false
  })
})
</script>

<style>
.scroll-container {
  height: 300px;
  overflow: hidden;
}

.scroll-item {
  height: 50px;
  line-height: 50px;
  border-bottom: 1px solid #eee;
}
</style>

API参数

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | el | HTMLElement | 必填 | 滚动容器元素 | | step | Number | 1 | 滚动步长，每次滚动的像素值 | | speed | Number | 30 | 滚动速度，滚动间隔时间(毫秒) | | isSeamless | Boolean | true | 是否开启无缝滚动循环 | | isMouseWheel | Boolean | true | 是否开启鼠标滚轮控制 | | hideScrollbarWidth | Boolean | false | 是否隐藏滚动条 |

使用注意事项

1. 容器高度：确保滚动容器有固定的高度，且内容高度大于容器高度
2. 子元素：滚动容器必须包含子元素，否则会报错
3. 无缝滚动：开启无缝滚动时，会自动复制一份原始内容实现循环效果
4. 鼠标悬停：鼠标悬停在容器上时会自动暂停滚动，移开后继续滚动

示例代码

基础示例

<div id="scroll-container" style="height: 200px;">
  <div>公告内容 1</div>
  <div>公告内容 2</div>
  <div>公告内容 3</div>
  <div>公告内容 4</div>
  <div>公告内容 5</div>
  <div>公告内容 6</div>
  <div>公告内容 7</div>
  <div>公告内容 8</div>
  <div>公告内容 9</div>
  <div>公告内容 10</div>
</div>

<script>
import { scrollList } from 'v3-scroll-list'

const container = document.getElementById('scroll-container')
scrollList({
  el: container,
  step: 1,
  speed: 50,
  isSeamless: true
})
</script>

快速滚动示例

scrollList({
  el: container,
  step: 3,        // 每次滚动3像素
  speed: 20,      // 每20毫秒滚动一次
  isSeamless: true,
  isMouseWheel: false  // 禁用鼠标滚轮
})

隐藏滚动条示例

scrollList({
  el: container,
  step: 1,
  speed: 30,
  isSeamless: true,
  isMouseWheel: true,
  hideScrollbarWidth: true  // 隐藏滚动条
})

许可证

MIT

作者

凌影