终极 Vue3-Marquee 教程：为 Vue 3 项目打造惊艳动态跑马灯效果 🚀

在现代网页设计中，动态效果是吸引用户注意力的关键。vue3-marquee 是一个专为 Vue 3 设计的零依赖跑马灯组件，它不仅简单易用，而且功能强大，能够为您的项目增添一抹动态的光彩。无论是新闻滚动、广告轮播还是通知展示，这个轻量级工具都能轻松胜任。

什么是 Vue3-Marquee？🌟

vue3-marquee 是一个零依赖的 Vue 3 跑马灯组件，最初是为内部使用而开发，但开发者意识到它可能对其他开发者也有价值，因此将其开源。该组件的设计灵感来源于 React 的 React Fast Marquee，通过创建内容的克隆来实现无缝过渡，确保动画的流畅性。

图：Vue3-Marquee 组件实现的流畅跑马灯效果示例

为什么选择 Vue3-Marquee？✨

✅ 零依赖，极速加载

组件体积小巧，不依赖任何第三方库，确保项目加载速度不受影响。核心源码位于 packages/vue3-marquee/src/，方便开发者深入学习和定制。

✅ 无缝动画过渡

通过智能内容克隆技术，实现无间断滚动效果，避免传统跑马灯常见的闪烁和空白问题。

✅ 高度可定制化

支持方向、速度、延迟、循环次数等多种自定义选项，满足不同场景需求。官方文档详细说明了所有 docs/2.api/ 中的属性和事件。

✅ 全场景响应式

自动适应各种屏幕尺寸，从手机到桌面设备均能完美展示。

快速安装步骤 🚀

Vue 3 项目一键安装

使用 npm 安装：

npm install vue3-marquee@latest --save

使用 yarn 安装：

yarn add vue3-marquee@latest

Nuxt 3 项目专属配置

安装依赖：

npm install vue3-marquee@latest --save

创建插件文件 plugins/Vue3Marquee.client.ts：

import Vue3Marquee from 'vue3-marquee'

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(Vue3Marquee, { name: 'Vue3Marquee' })
})

基础使用教程 📖

最简单的实现代码

<template>
  <Vue3Marquee>
    <img height="200" width="300" src="your-image.jpg" alt="滚动图片" />
    <img height="200" width="300" src="your-image-2.jpg" alt="滚动图片" />
    <img height="200" width="300" src="your-image-3.jpg" alt="滚动图片" />
  </Vue3Marquee>
</template>

<script>
import { Vue3Marquee } from 'vue3-marquee'

export default {
  components: {
    Vue3Marquee,
  },
}
</script>

常用配置参数说明

参数	类型	默认值	描述
direction	String	'left'	滚动方向：'left'、'right'、'up'、'down'
speed	Number	50	滚动速度（像素/秒）
delay	Number	0	开始滚动前延迟（毫秒）
loop	Number	0	滚动次数（0 为无限循环）

完整 API 文档参见 docs/2.api/1.props.md

实用场景示例 💡

新闻标题滚动

<Vue3Marquee speed="60">
  <span>📢 最新公告：Vue3-Marquee v4.0 版本发布！</span>
  <span>🔥 热门文章：如何优化 Vue 项目性能</span>
  <span>🎉 活动预告：前端技术分享会将于下周举行</span>
</Vue3Marquee>

图片轮播展示

<Vue3Marquee direction="right" pauseOnHover>
  <img src="product-1.jpg" alt="产品展示" />
  <img src="product-2.jpg" alt="产品展示" />
  <img src="product-3.jpg" alt="产品展示" />
</Vue3Marquee>

更多示例代码可在 docs/3.examples.md 中查看

常见问题解答 ❓

如何实现鼠标悬停暂停？

只需添加 pauseOnHover 属性：

<Vue3Marquee pauseOnHover>...</Vue3Marquee>

能否垂直滚动内容？

当然可以！设置 direction="up" 或 direction="down" 即可实现垂直滚动。

如何调整滚动速度？

通过 speed 属性设置，数值越大滚动越快：

<Vue3Marquee speed="80">...</Vue3Marquee>

结语

vue3-marquee 是一个功能强大且易于使用的 Vue 3 跑马灯组件，它不仅能够为您的项目增添动态效果，还能通过其高度可定制的特性满足各种需求。无论您是开发新闻网站、电商平台还是企业内部系统，vue3-marquee 都能成为您的得力助手。立即尝试，让您的项目焕发新的活力！

官方文档：docs/ 示例项目：packages/playground/