A Vue 3 auto scroll component with seamless loop, hover pause, wheel control, and single step mode support
npm install vue-seamless-autoscrollbash
npm install vue-seamless-autoscroll
`
或使用其他包管理器:
`bash
使用 yarn
yarn add vue-seamless-autoscroll
使用 pnpm
pnpm add vue-seamless-autoscroll
`
🔨 快速开始
$3
`typescript
import { createApp } from 'vue';
import VueSeamlessAutoscroll from 'vue-seamless-autoscroll';
const app = createApp(App);
app.use(VueSeamlessAutoscroll);
// 或使用自定义组件名
app.use(VueSeamlessAutoscroll, {
name: 'VueSeamlessAutoscroll', // 自定义组件名称
});
`
$3
`vue
`
📝 基础用法
$3
`vue
{{ item.title }}
`
$3
`vue
公告 1
公告 2
公告 3
`
$3
`vue
:list="horizontalData"
scroll-direction="left"
:steep="2"
class="horizontal-scroll"
>
{{ item.text }}
`
$3
`vue
`
$3
`vue
{{ item.title }}
{{ item.title }}
:list="listData"
:item-style="{ padding: '20px', backgroundColor: '#f5f5f5' }"
>
{{ item.title }}
{{ item.title }}
`
📚 API 参考
$3
| 参数 | 类型 | 默认值 | 说明 |
| ---------------------- | ------------------------------------------------------------ | ----------- | ------------------------------------ |
| list | any[] | undefined | 滚动数据数组,不传则使用插槽模式 |
| steep | number | 0.5 | 滚动速度(像素/帧) |
| scrollDirection | 'top' \| 'bottom' \| 'left' \| 'right' | 'top' | 滚动方向 |
| isRoller | boolean | true | 是否启用鼠标滚轮控制 |
| rollerScrollDistance | number | 20 | 鼠标滚轮滚动距离 |
| isHoverStop | boolean | false | 鼠标移出后是否保持停止 |
| itemKey | string \| ((item: any, index: number) => string \| number) | undefined | 列表项的 key |
| autoPlay | boolean | true | 挂载后是否自动开始滚动 |
| autoPlayDelay | number | 0 | 自动开始前的延迟时间(毫秒) |
| forceScroll | boolean | false | 内容未超出容器时是否强制滚动 |
| isSingleStep | boolean | false | 是否启用单步滚动模式 |
| singleStepDistance | number | 0 | 单步滚动距离(像素),0 表示自动计算 |
| singleStepDelay | number | 1500 | 单步滚动后的停顿时间(毫秒) |
| seamless | boolean | true | 是否开启无缝滚动 |
| wheelResumeDelay | number | 300 | 滚轮停止后自动恢复滚动的延迟(毫秒) |
| alwaysStop | boolean | false | 是否强制停止自动滚动 |
| itemClass | string \| string[] | undefined | 自定义滚动项的 CSS 类名 |
| itemStyle | Record | undefined | 自定义滚动项的内联样式 |
$3
#### scrollItem(作用域插槽)
当提供 list 属性时使用。
`vue
`
| 插槽参数 | 类型 | 说明 |
| -------- | -------- | ---------- |
| item | any | 当前项数据 |
| index | number | 当前项索引 |
#### default 插槽
当不提供 list 属性时使用。
`vue
自定义内容 1
自定义内容 2
自定义内容 3
`
$3
通过模板 ref 访问:
`vue
`
| 方法 | 说明 |
| ------------ | ------------------------------------ |
| start() | 开始滚动 |
| stop() | 停止滚动 |
| initData() | 重新初始化组件(重新计算尺寸并重启) |
| resize() | 手动重新计算尺寸 |
$3
完整的 TypeScript 支持:
`typescript
import { VueSeamlessAutoscroll } from 'vue-seamless-autoscroll';
interface MyItem {
id: number;
title: string;
}
const items = ref([...]);
`
🎨 样式自定义
组件包含最小化的默认样式,你可以覆盖它们:
`scss
// 容器
.custom-list {
// 自定义样式
}
// 滚动内容包装器
.scroll-content {
// 自定义样式
}
// 内容主体
.list-body {
// 自定义样式
}
/ 横向滚动 /
.list-content-horizontal {
display: flex;
flex-direction: row;
}
`
🔧 高级用法
$3
组件自动检测内容是否超出容器,仅在需要时启用滚动:
`vue
`
$3
使用 force-scroll 无论内容大小都启用滚动:
`vue
`
$3
v1.0.1+ 版本提供了防抖工具函数:
`typescript
import { debounce } from 'vue-seamless-autoscroll/utils';
const debouncedFn = debounce(() => {
console.log('我将延迟 300ms 执行');
}, 300);
`
❓ 常见问题
$3
A: 对于横向滚动(scroll-direction="left" 或 "right"),你可能需要设置 :force-scroll="true" 来强制启用滚动。这是因为浏览器的横向内容溢出检测可能会受到 CSS flexbox 布局的影响。
`vue
:list="horizontalData"
scroll-direction="left"
:force-scroll="true"
:steep="2"
>
`
如果横向内容仍然不滚动,请检查:
1. 确保容器有固定宽度
2. 确保子元素设置了正确的 display: inline-block 或 flex: 0 0 auto
3. 确保横向内容应用了 white-space: nowrap
📄 许可证
MIT
---
🤝 贡献
欢迎提交 Issue 和 Pull Request!
📝 更新日志
$3
- ✅ 新增 itemClass 属性,支持自定义滚动项的 CSS 类名
- ✅ 新增 itemStyle 属性,支持自定义滚动项的内联样式
- ✅ 修复单步模式下的内存泄漏问题(正确清理重置定时器)
- ✅ 优化单步过渡动画时长,提取为常量
$3
- ✅ CSS 打包进 JS 文件(无需单独引入 CSS)
- ✅ 添加常见问题文档,说明横向滚动需要开启 force-scroll
- ✅ 使用 vite-plugin-css-injected-by-js` 优化构建配置