scroll-seamless

v1.3.2TypeScript

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

seamless scroll marquee vue react typescript

0/weekUpdated 5 months agoBSD-3-ClauseUnpacked: 805.0 KB

npm install scroll-seamless

Scroll Seamless

![npm version](https://www.npmjs.com/package/scroll-seamless)
![npm downloads](https://www.npmjs.com/package/scroll-seamless)
![License](https://github.com/chao921125/scroll-seamless/blob/main/LICENSE)

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

简介

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

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

特性

$3

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

$3

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

$3

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

$3

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

安装

$3

``bash npm install scroll-seamless`

`$3`

`bash yarn add scroll-seamless`

`$3`

`bash pnpm add scroll-seamless`

`$3`

`html`

`使用方法`

`$3`

`jsx 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 (


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


        )}
      
      {/ 控制按钮 /}


  );
};

$3

`vue

`$3`

`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 参数来控制：

`jsx // React 多行多列示例 {(item, index, rowIndex, colIndex) => (


      {item} (行: {rowIndex}, 列: {colIndex})

)}

`vue`

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

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

`javascript 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 组件核心样式只保证功能性（布局、溢出、内容复制），所有视觉样式均可由用户自定义。

`$3`

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

示例：

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

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

`$3`

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

示例：

`vue :data="data" class="my-scroll-root" :style="{ border: '1px solid #f00' }" content-class="my-content" item-class="my-item" >`

`浏览器兼容性`

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

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

`常见问题解答`

`$3`

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

`$3`

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

`$3`

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

$3

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

文档

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

许可证

BSD-3-Clause

Scroll Seamless

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

简介

特性

$3

安装

$3

``bash npm install scroll-seamless`

`$3`

`bash yarn add scroll-seamless`

`$3`

`bash pnpm add scroll-seamless`

`$3`

`html`

`使用方法`

`$3`

`jsx 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 (


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


        )}
      
      {/ 控制按钮 /}