scroll-seamless

v1.3.2

Published

4 months ago

A seamless scroll library for JS, Vue, and React.

0High
0Medium
0Low

hcprecog

seamless scroll marquee vue react typescript

Scroll Seamless

一个高性能、功能丰富的无缝滚动库，支持 JavaScript、Vue3 和 React，适用于各种滚动展示场景。

简介

Scroll Seamless 是一个专为现代 Web 应用设计的无缝滚动库，提供了流畅的滚动体验和丰富的自定义选项。无论是简单的文本轮播，还是复杂的数据展示，Scroll Seamless 都能满足您的需求。支持多种框架集成，性能优化，以及大数据量处理。

本库专注于提供高性能、低内存占用的滚动解决方案，通过优化的渲染策略和内存管理，即使在移动设备上也能保持流畅的滚动体验。同时，丰富的 API 和插件系统使其能够适应各种复杂场景的需求。

特性

核心功能

🚀 高性能无缝滚动 - 优化的渲染和动画，确保流畅的滚动体验
🎯 多方向支持 - 灵活支持上/下/左/右四个方向的滚动
🔄 真正的无缝衔接 - 精确计算确保无空白间隙，完美循环
🧩 多行多列布局 - 支持复杂的网格布局，满足多样化展示需求

用户体验

🖱️ 交互控制 - 鼠标悬停暂停、滚轮控制等交互功能
📱 响应式设计 - 自适应不同屏幕尺寸，完美适配移动设备
♿ 无障碍功能 - 支持屏幕阅读器和键盘导航，提升可访问性
🎛️ 丰富的配置选项 - 可定制的速度、间隔、动画效果等参数

开发友好

🎨 统一的渲染模式 - 在 React（函数式 children）和 Vue（作用域插槽）中保持一致的 API
🔧 TypeScript 支持 - 完整的类型定义，提供良好的开发体验
🔌 插件系统 - 可扩展的插件架构，轻松添加自定义功能
📊 性能监控 - 内置性能分析工具，帮助优化应用

高级特性

⚡ 虚拟滚动 - 高效处理大数据量（10000+ 条），显著提升性能
🧩 自定义渲染 - 完全控制每个滚动项的渲染方式
🔄 数据驱动更新 - 响应式数据变化，自动更新滚动内容
🛠️ 丰富的 API - 提供全面的方法和事件，满足复杂场景需求

安装

NPM

npm install scroll-seamless

Yarn

yarn add scroll-seamless

PNPM

pnpm add scroll-seamless

CDN

<script src="https://unpkg.com/scroll-seamless/dist/scroll-seamless.min.js"></script>

使用方法

React 组件

import React, { useRef } from "react";
import { ScrollSeamless } from "scroll-seamless/react";

const MyComponent = () => {
  const scrollRef = useRef(null);
  const data = ["Item 1", "Item 2", "Item 3", "Item 4", "Item 5"];

  return (
    <div style={{ width: "300px", height: "50px" }}>
      <ScrollSeamless
        ref={scrollRef}
        data={data}
        direction="right"
        step={1}
        hoverStop={true}
        wheelEnable={true}
        rows={1}
        cols={1}
        itemClass="custom-item-class"
      >
        {/* 函数式 children - 渲染单个项目 */}
        {(item, index) => (
          <div
            key={index}
            style={{
              padding: "10px",
              margin: "0 5px",
              backgroundColor: "#f0f0f0",
              borderRadius: "4px",
            }}
          >
            {item}
          </div>
        )}
      </ScrollSeamless>

      {/* 控制按钮 */}
      <div className="controls">
        <button onClick={() => scrollRef.current?.start()}>开始</button>
        <button onClick={() => scrollRef.current?.stop()}>停止</button>
        <button onClick={() => scrollRef.current?.updateData()}>
          更新数据
        </button>
      </div>
    </div>
  );
};

Vue 组件

<template>
  <div style="width: 300px; height: 50px;">
    <ScrollSeamless
      ref="scrollRef"
      :data="data"
      direction="right"
      :step="1"
      :hover-stop="true"
      :wheel-enable="true"
      :rows="1"
      :cols="1"
      item-class="custom-item-class"
      v-model="isScrolling"
    >
      <!-- 作用域插槽 - 渲染单个项目 -->
      <template #default="{ item, index }">
        <div
          :key="index"
          style="
          padding: 10px; 
          margin: 0 5px; 
          background-color: #f0f0f0;
          border-radius: 4px;
        "
        >
          {{ item }}
        </div>
      </template>
    </ScrollSeamless>

    <!-- 控制按钮 -->
    <div class="controls">
      <button @click="startScroll">开始</button>
      <button @click="stopScroll">停止</button>
      <button @click="updateScrollData">更新数据</button>
    </div>
  </div>
</template>

<script>
import { ref } from "vue";
import { ScrollSeamless } from "scroll-seamless/vue";

export default {
  components: { ScrollSeamless },
  setup() {
    const scrollRef = ref(null);
    const data = ref(["Item 1", "Item 2", "Item 3", "Item 4", "Item 5"]);
    const isScrolling = ref(true);

    const startScroll = () => {
      scrollRef.value?.start();
    };

    const stopScroll = () => {
      scrollRef.value?.stop();
    };

    const updateScrollData = () => {
      data.value = [...data.value, "New Item " + (data.value.length + 1)];
      scrollRef.value?.updateData();
    };

    return {
      scrollRef,
      data,
      isScrolling,
      startScroll,
      stopScroll,
      updateScrollData,
    };
  },
};
</script>

JavaScript 核心库

import { ScrollSeamless } from "scroll-seamless/core";

const container = document.getElementById("scroll-container");
const scrollInstance = new ScrollSeamless(container, {
  data: ["Item 1", "Item 2", "Item 3", "Item 4", "Item 5"],
  direction: "right",
  step: 1,
  hoverStop: true,
  wheelEnable: true,
  rows: 1,
  cols: 1,
  plugins: [], // 可选：添加自定义插件
  performance: { enabled: true }, // 启用性能监控
  accessibility: { enabled: true }, // 启用无障碍功能
});

// 控制方法
scrollInstance.start();
scrollInstance.stop();
scrollInstance.updateData();
scrollInstance.destroy();

// 获取状态
const position = scrollInstance.getPosition();
const isRunning = scrollInstance.isRunning();

// 设置选项
scrollInstance.setOptions({
  step: 2,
  direction: "left",
});

多行多列布局

Scroll Seamless 支持多行多列布局，可以通过 rows 和 cols 参数来控制：

// React 多行多列示例
<ScrollSeamless data={data} direction="left" rows={2} cols={2}>
  {(item, index, rowIndex, colIndex) => (
    <div key={index}>
      {item} (行: {rowIndex}, 列: {colIndex})
    </div>
  )}
</ScrollSeamless>

<!-- Vue 多行多列示例 -->
<ScrollSeamless :data="data" direction="left" :rows="2" :cols="2">
  <template #default="{ item, index, rowIndex, colIndex }">
    <div :key="index">
      {{ item }} (行: {{ rowIndex }}, 列: {{ colIndex }})
    </div>
  </template>
</ScrollSeamless>

虚拟滚动（大数据量优化）

对于大数据量场景（如 10000+ 条数据），可以使用虚拟滚动插件来优化性能：

import { ScrollSeamless } from "scroll-seamless/core";
import { createVirtualScrollPlugin } from "scroll-seamless/plugins";

// 创建虚拟滚动插件
const virtualScrollPlugin = createVirtualScrollPlugin({
  enabled: true,
  itemWidth: 200, // 每个 item 宽度
  itemHeight: 40, // 每个 item 高度
  bufferSize: 10, // 缓冲区大小
  onRender: (startIndex, endIndex, visibleCount) => {
    console.log(
      `渲染范围: ${startIndex} - ${endIndex}, 可见数量: ${visibleCount}`
    );
  },
});

// 使用插件
const scrollInstance = new ScrollSeamless(container, {
  data: largeData, // 大数据量
  plugins: [virtualScrollPlugin],
  onEvent: (event, data) => {
    if (event === "virtual-scroll-update") {
      console.log("性能指标:", data);
    }
  },
});

性能对比：

传统渲染：需要渲染 数据量 × 2 个 DOM 节点
虚拟滚动：只渲染可视区域 + 缓冲区的节点
性能提升：显著减少内存占用和渲染时间

自定义样式

Scroll Seamless 组件核心样式只保证功能性（布局、溢出、内容复制），所有视觉样式均可由用户自定义。

React 自定义样式

className/style：作用于最外层容器
contentClassName：作用于每个内容区（.ss-content）
itemClassName：作用于每个单项

示例：

<ScrollSeamless
  data={data}
  className="my-scroll-root"
  style={{ border: "1px solid #f00" }}
  contentClassName="my-content"
  itemClassName="my-item"
>
  {(item) => <span>{item}</span>}
</ScrollSeamless>

.my-scroll-root {
  background: #fafafa;
}
.my-content {
  padding: 8px 0;
}
.my-item {
  color: #1976d2;
  font-weight: bold;
}

Vue 自定义样式

class/style：作用于最外层容器
content-class：作用于每个内容区（.ss-content）
item-class：作用于每个单项

示例：

<ScrollSeamless
  :data="data"
  class="my-scroll-root"
  :style="{ border: '1px solid #f00' }"
  content-class="my-content"
  item-class="my-item"
>
  <template #default="{ item }">
    <span>{{ item }}</span>
  </template>
</ScrollSeamless>

浏览器兼容性

Scroll Seamless 支持所有现代浏览器，包括：

| Chrome | Firefox | Safari | Edge | IE | Opera | | ------ | ------- | ------ | ---- | --- | ----- | | 60+ | 60+ | 12+ | 79+ | 11+ | 50+ |

常见问题解答

Q: 如何在动态数据变化时更新滚动内容？

A: 当数据发生变化时，调用组件实例的 updateData() 方法即可重新渲染内容。

Q: 如何控制滚动速度？

A: 通过 step 参数控制每一步的像素移动量，数值越大滚动越快。

Q: 如何在特定条件下暂停滚动？

A: 除了 hoverStop 参数外，您还可以随时调用 stop() 和 start() 方法来控制滚动状态。

Q: 如何处理大量数据的性能问题？

A: 对于大数据量场景，请使用虚拟滚动插件，它可以显著减少 DOM 节点数量，提高性能。

文档

快速入门 - 快速上手指南
API 文档 - 详细的 API 参考
API 文档（英文） - API 参考（英文版）
React 集成指南 - React 组件详细使用说明
Vue 集成指南 - Vue 组件详细使用说明
贡献指南 - 如何参与项目开发
贡献指南（英文） - 如何参与项目开发（英文版）
安全政策 - 安全漏洞报告流程
插件系统 - 插件系统使用和开发指南
虚拟滚动 - 虚拟滚动功能详解

许可证

BSD-3-Clause