@seamless-scroll/core

无缝滚动的核心功能实现，提供与框架无关的滚动逻辑。

介绍

@seamless-scroll/core 提供了实现无缝滚动所需的全部核心逻辑，包括:

• 滚动状态管理
• 滚动动画控制
• 尺寸计算
• 智能克隆数量计算
• 事件处理

此包可以直接使用，也可以作为构建更高级UI组件的基础。

安装

npm install @seamless-scroll/core
# 或
pnpm add @seamless-scroll/core
# 或
yarn add @seamless-scroll/core

API 文档

createSeamlessScroll 函数

这是核心包的主要入口函数，用于创建无缝滚动实例。

参数

function createSeamlessScroll(
  container: HTMLElement,
  content: HTMLElement,
  realList: HTMLElement,
  options?: ScrollOptions,
  events?: ScrollEvents,
  onStateChange?: (state: ScrollState) => void,
): SeamlessScrollResult;

• container: 容器元素，通常是有固定尺寸且溢出隐藏的外部容器
• content: 内容元素，包含需要滚动的实际内容
• realList: 滚动内容元素，包含需要滚动的实际内容
• options: 滚动配置选项，可选
• events: 事件回调函数，可选
• onStateChange: 状态改变时的回调，可选

返回值

函数返回一个包含以下属性的对象：

• state: 只读的滚动状态对象
• methods: 控制滚动的方法集合
• destroy: 销毁滚动实例的函数

配置选项 (ScrollOptions)

| 参数 | 类型 | 默认值 | 描述 | | ---------------- | ------------------------------ | ------------ | ---------------------------------- | | direction | 'vertical' | 'horizontal' | 'vertical' | 滚动方向 | | speed | number | 60 | 滚动速度（像素/秒） | | duration | number | 1000 | 每次滚动动画的持续时间（毫秒） | | pauseTime | number | 0 | 每次滚动后的暂停时间（毫秒） | | hoverPause | boolean | true | 是否在鼠标悬停时暂停 | | autoScroll | boolean | true | 是否自动开始滚动 | | step | number | 0 | 滚动步长，0表示自动计算 | | forceScrolling | boolean | false | 是否强制滚动（即使内容未超出容器） |

状态对象 (ScrollState)

| 属性 | 类型 | 描述 | | ---------------- | --------- | ------------ | | isScrolling | boolean | 是否正在滚动 | | isPaused | boolean | 是否暂停 | | isHovering | boolean | 鼠标是否悬停 | | scrollDistance | number | 滚动距离 | | contentSize | number | 内容尺寸 | | containerSize | number | 容器尺寸 | | isScrollNeeded | boolean | 是否需要滚动 | | minClones | number | 最小克隆数量 |

方法对象 (ScrollMethods)

| 方法 | 描述 | | ------------------------ | ------------ | | start() | 开始滚动 | | stop() | 停止滚动 | | pause() | 暂停滚动 | | resume() | 恢复滚动 | | reset() | 重置滚动位置 | | forceScroll() | 强制开始滚动 | | updateSize() | 更新尺寸计算 | | updateOptions(options) | 更新配置参数 |

事件回调 (ScrollEvents)

| 事件 | 参数 | 描述 | | ------------- | ----------------------------------------------- | ---------------- | | onScroll | (distance: number, direction: string) => void | 滚动事件回调 | | onItemClick | (item: any, index: number) => void | 点击项目时的回调 |

基本用法

也可以查看Github上的exmaples。

import { createSeamlessScroll } from "@seamless-scroll/core";

// 获取DOM元素
const container = document.querySelector(".scroll-container");
const content = document.querySelector(".scroll-content");
const realList = document.querySelector(".real-list");

// 创建无缝滚动实例
const { state, methods, destroy } = createSeamlessScroll(
  container,
  content,
  realList,
  {
    direction: "vertical",
    speed: 60,
    hoverPause: true,
  },
  {
    onScroll: (distance, direction) => {
      console.log(`滚动距离: ${distance}`);
    },
    onItemClick: (item, index) => {
      console.log(`点击了第 ${index} 项`, item);
    },
  },
);

// 控制滚动
methods.start(); // 开始滚动
methods.pause(); // 暂停滚动
methods.resume(); // 恢复滚动
methods.stop(); // 停止滚动

// 访问状态
console.log("内容尺寸:", state.contentSize);
console.log("容器尺寸:", state.containerSize);
console.log("是否需要滚动:", state.isScrollNeeded);

// 更新配置
methods.updateOptions({ speed: 100 });

// 销毁实例
destroy();

许可证

MIT