vue-seamless-autoscroll

---

功能特性

- ✅ 无缝循环 - 连续滚动无中断
- ✅ 多方向支持 - 支持上下左右滚动
- ✅ 悬停暂停 - 鼠标移入暂停，移出恢复
- ✅ 滚轮控制 - 支持鼠标滚轮手动滚动
- ✅ 单步模式 - 固定距离滚动并停顿
- ✅ 灵活的数据 - 支持数组数据或插槽内容
- ✅ 完整 TypeScript - 使用 TypeScript 编写，提供完整类型定义
- ✅ 灵活控制 - 暴露方法供外部控制
- ✅ 智能检测 - 自动检测内容溢出
- ✅ 轻量级 - 无外部依赖（除 Vue 外）

---

📦 安装

``bash
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





`

$3

`vue

`

$3

`vue



`

$3

`vue



`

$3

`vue



`

📚 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 \| string | 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` 优化构建配置

$3

- ✅ 初始版本，支持无缝滚动、悬停暂停、滚轮控制、单步模式