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

写前端的阿海
0 阅读3分钟

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

运行效果

前言

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

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

项目介绍

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

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

安装

npm install zzy-scroll-timer

使用方法

Vue 3

<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

<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

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>
  );
}

参数说明

参数类型说明默认值
intervalnumber滚动间隔时间（毫秒）2500
directionstring滚动方向：'up' 或 'down''up'
scrollPxnumber每次滚动的像素数，默认使用子元素高度0
transitionDurationnumber过渡动画持续时间（毫秒）300
transitionTimingFunctionstring过渡动画 timing 函数'ease-in-out'
transitionstring完整的过渡动画设置，优先级更高-
immediateboolean是否立即开始第一次滚动false
autoStartboolean是否自动开始滚动true

方法说明

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

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

各框架调用方式

Vue 2:

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

Vue 3:

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

React:

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

动态更新

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

  • 方向变更：会重置滚动位置并保留原始子元素结构
  • 其他参数变更：会销毁旧实例并创建新实例
<!-- 动态修改方向 -->
<ZScrollTimerVue3 
  :direction="currentDirection"
  :interval="currentInterval"
/>

实现原理

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

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

核心代码结构：

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;
    }
  }
}

应用场景

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

项目地址

总结

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

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

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

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

avatar
文章
阅读
粉丝