# vue3-scroll

**Repository Path**: XiXiaoFan/vue3-scroll

## Basic Information

- **Project Name**: vue3-scroll
- **Description**: 无缝滚动组件，适用于数据大屏等，需要纵向或横向滚动的场景
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-22
- **Last Updated**: 2025-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue3-scroll-animation

本项目是一个基于 Vue3 的滚动组件库，提供简单易用的自动滚动功能，支持垂直和水平两种滚动模式。

## 特性

- 🚀 轻量级，无额外依赖
- 📱 响应式设计，自适应容器大小
- ⚙️ 可配置滚动速度和方向
- 🎯 支持鼠标悬停暂停
- 🔄 自动检测内容是否需要滚动
- 🎨 支持垂直和水平滚动模式
- 📦 TypeScript 支持

## 安装

```bash
npm install vue3-scroll-animation
```

## 基本用法

```vue
<template>
  <div style="height: 200px; width: 300px;">
    <Vue3ScrollAnimation>
      <div>
        <p>这是第一行内容</p>
        <p>这是第二行内容</p>
        <p>这是第三行内容</p>
        <!-- 更多内容... -->
      </div>
    </Vue3ScrollAnimation>
  </div>
</template>

<script setup>
import { Vue3ScrollAnimation } from 'vue3-scroll-animation';
</script>
```

## API 文档

### Props

| 属性名 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| `hover` | `boolean` | `true` | 是否在鼠标悬停时暂停滚动动画 |
| `step` | `number` | `5` | 滚动速度步进值，值越大滚动越快 |
| `horizontal` | `boolean` | `false` | 是否使用水平滚动模式，默认垂直滚动 |
| `durationFactor` | `number` | `10` | 动画持续时间计算系数，调整滚动速度比例 |

### 插槽

组件默认插槽用于放置需要滚动的内容。

```vue
<Vue3ScrollAnimation>
  <!-- 这里放置你的内容 -->
  <div>滚动内容...</div>
</Vue3ScrollAnimation>
```

## 示例

### 垂直滚动示例

```vue
<template>
  <div style="height: 200px; width: 300px; border: 1px solid #ccc;">
    <Vue3ScrollAnimation :step="3">
      <div style="padding: 10px;">
        <p>📝 垂直滚动内容示例</p>
        <p>这是第一行内容</p>
        <p>这是第二行内容</p>
        <p>这是第三行内容</p>
        <p>这是第四行内容</p>
        <p>这是第五行内容</p>
        <p>这是第六行内容</p>
        <p>这是第七行内容</p>
        <p>这是第八行内容</p>
      </div>
    </Vue3ScrollAnimation>
  </div>
</template>

<script setup>
import { Vue3ScrollAnimation } from 'vue3-scroll-animation';
</script>
```

### 水平滚动示例

```vue
<template>
  <div style="height: 100px; width: 300px; border: 1px solid #ccc;">
    <Vue3ScrollAnimation :horizontal="true" :step="2">
      <div style="padding: 10px; white-space: nowrap;">
        <span>🔄 水平滚动内容示例 </span>
        <span>这是第一段内容 </span>
        <span>这是第二段内容 </span>
        <span>这是第三段内容 </span>
        <span>这是第四段内容 </span>
        <span>这是第五段内容 </span>
      </div>
    </Vue3ScrollAnimation>
  </div>
</template>

<script setup>
import { Vue3ScrollAnimation } from 'vue3-scroll-animation';
</script>
```

### 禁用悬停暂停示例

```vue
<template>
  <div style="height: 200px; width: 300px; border: 1px solid #ccc;">
    <Vue3ScrollAnimation :hover="false">
      <div style="padding: 10px;">
        <p>🚫 禁用悬停暂停示例</p>
        <p>即使鼠标悬停也不会暂停滚动</p>
        <p>这是第三行内容</p>
        <p>这是第四行内容</p>
        <p>这是第五行内容</p>
      </div>
    </Vue3ScrollAnimation>
  </div>
</template>

<script setup>
import { Vue3ScrollAnimation } from 'vue3-scroll-animation';
</script>
```

### 自定义滚动速度示例

```vue
<template>
  <div style="height: 200px; width: 300px; border: 1px solid #ccc;">
    <Vue3ScrollAnimation :step="10" :durationFactor="5">
      <div style="padding: 10px;">
        <p>⚡ 快速滚动示例</p>
        <p>这是第一行内容</p>
        <p>这是第二行内容</p>
        <p>这是第三行内容</p>
        <p>这是第四行内容</p>
        <p>这是第五行内容</p>
      </div>
    </Vue3ScrollAnimation>
  </div>
</template>

<script setup>
import { Vue3ScrollAnimation } from 'vue3-scroll-animation';
</script>
```

## 工作原理

1. **内容检测**：组件会自动检测内容是否超出容器大小，只有超出时才会启动滚动动画
2. **内容克隆**：当需要滚动时，组件会克隆一份内容，实现无缝滚动效果
3. **响应式**：使用 ResizeObserver 监听内容变化，自动调整滚动状态
4. **性能优化**：使用 requestAnimationFrame 优化性能，避免频繁计算

## 注意事项

- 确保容器有固定的高度（垂直滚动）或宽度（水平滚动）
- 内容超出容器大小时才会启动滚动动画
- 组件会自动处理内容变化和窗口大小变化

## License

MIT