zzy-scroll-timer：一个跨框架的滚动定时器插件

前言

在前端开发中，滚动列表是一个常见的需求场景，比如公告栏滚动、新闻轮播、数据展示等。虽然市面上有不少轮播组件，但专门针对上下滚动且支持多框架的轻量级插件却不多见。

今天给大家分享一个我开发的跨框架滚动定时器插件 ------ zzy-scroll-timer，它支持 Vue 2、Vue 3 和 React，使用简单，功能强大。

项目介绍

zzy-scroll-timer 是一个轻量级的滚动定时器插件，主要特点：

✅ 跨框架支持：同时支持 Vue 2、Vue 3 和 React
✅ 双向滚动：支持向上和向下两种滚动方向
✅ 自动/手动控制：支持自动开始滚动，也支持手动控制
✅ 动态参数更新：所有参数都支持动态修改
✅ TypeScript 支持：完整的类型定义
✅ 轻量级：核心代码简洁，无额外依赖

安装

bash 复制代码

npm install zzy-scroll-timer

使用方法

Vue 3

vue 复制代码

<template>
  <ZScrollTimerVue3 :interval="2000" direction="up">
    <ZScrollTimerItem>
      <div class="item">Item 1</div>
    </ZScrollTimerItem>
    <ZScrollTimerItem>
      <div class="item">Item 2</div>
    </ZScrollTimerItem>
  </ZScrollTimerVue3>
</template>

<script setup>
import { ZScrollTimerVue3, ZScrollTimerItem } from 'zzy-scroll-timer/vue3';
</script>

Vue 2

vue 复制代码

<template>
  <ZScrollTimerVue2 :interval="2000" direction="up">
    <ZScrollTimerItem>
      <div class="item">Item 1</div>
    </ZScrollTimerItem>
    <ZScrollTimerItem>
      <div class="item">Item 2</div>
    </ZScrollTimerItem>
  </ZScrollTimerVue2>
</template>

<script>
import { ZScrollTimerVue2, ZScrollTimerItem } from 'zzy-scroll-timer/vue2';

export default {
  components: { ZScrollTimerVue2, ZScrollTimerItem }
}
</script>

React

jsx 复制代码

import { ZScrollTimerReact, ZScrollTimerItem } from 'zzy-scroll-timer/react';

function App() {
  return (
    <ZScrollTimerReact interval={2000} direction="up">
      <ZScrollTimerItem>
        <div className="item">Item 1</div>
      </ZScrollTimerItem>
      <ZScrollTimerItem>
        <div className="item">Item 2</div>
      </ZScrollTimerItem>
    </ZScrollTimerReact>
  );
}

参数说明

参数	类型	说明	默认值
interval	number	滚动间隔时间（毫秒）	2500
direction	string	滚动方向：'up' 或 'down'	'up'
scrollPx	number	每次滚动的像素数，默认使用子元素高度	0
transitionDuration	number	过渡动画持续时间（毫秒）	300
transitionTimingFunction	string	过渡动画 timing 函数	'ease-in-out'
transition	string	完整的过渡动画设置，优先级更高	-
immediate	boolean	是否立即开始第一次滚动	false
autoStart	boolean	是否自动开始滚动	true

方法说明

通过 ref 可以调用以下方法：

方法	说明
start()	开始滚动
stop()	停止滚动

各框架调用方式

Vue 2:

javascript 复制代码

this.$refs.scrollTimerRef.start();
this.$refs.scrollTimerRef.stop();

Vue 3:

javascript 复制代码

scrollTimerRef.value?.start();
scrollTimerRef.value?.stop();

React:

javascript 复制代码

scrollTimerRef.current?.start();
scrollTimerRef.current?.stop();

动态更新

组件支持动态更新所有参数，当参数变化时会自动重新初始化：

方向变更：会重置滚动位置并保留原始子元素结构
其他参数变更：会销毁旧实例并创建新实例

vue 复制代码

<!-- 动态修改方向 -->
<ZScrollTimerVue3 
  :direction="currentDirection"
  :interval="currentInterval"
/>

实现原理

zzy-scroll-timer 的核心实现思路：

克隆子元素：为了实现无缝滚动，会将第一个子元素克隆一份放到最后
定时器控制 ：使用 setTimeout 控制滚动间隔
CSS 过渡 ：使用 transform 和 transition 实现平滑滚动动画

核心代码结构：

typescript 复制代码

class ScrollTimer {
  private element: HTMLElement;
  private options: ScrollTimerOptions;
  private timer: number | null = null;
  
  constructor(element: HTMLElement, options: ScrollTimerOptions) {
    this.element = element;
    this.options = options;
    this.init();
  }
  
  private init() {
    // 克隆第一个子元素实现无缝滚动
    this.cloneFirstChild();
    // 开始定时滚动
    this.startTimer();
  }
  
  public start() {
    this.startTimer();
  }
  
  public stop() {
    if (this.timer) {
      clearTimeout(this.timer);
      this.timer = null;
    }
  }
}

应用场景

公告栏滚动：网站首页的公告通知滚动展示
新闻轮播：新闻列表的自动滚动展示
数据展示：实时数据的滚动展示
排行榜：用户排行榜的滚动展示
消息通知：系统消息的滚动提示

项目地址

Gitee : zzy-scroll-timer
NPM : zzy-scroll-timer

总结

zzy-scroll-timer 是一个简单实用的滚动定时器插件，它的优势在于：

跨框架支持，一套代码适配 Vue 2/3 和 React
API 设计简洁，上手容易
功能完善，支持自动/手动控制和动态更新
TypeScript 支持，类型安全

如果你正在寻找一个轻量级的滚动组件，不妨试试 zzy-scroll-timer！

如果这篇文章对你有帮助，欢迎点赞、收藏、评论！ 🎉