往下滑动查看动画

scroll-frame-canvas

高性能的滚动驱动帧序列动画库，让你的网页体验更加生动

GitHub 仓库

🎬 演示素材来源

本演示的动画素材来源于 Adaline

关于 Adaline

Adaline 是专为世界级产品和工程团队打造的端到端 LLM 开发平台，提供迭代、评估、部署和监控的完整解决方案。

访问 Adaline →

🎛️ 帧数控制

🚀 高性能渲染

使用 OffscreenCanvas 预渲染所有帧，运行时直接绘制 ImageBitmap，确保丝滑的滚动体验。

⚡ 自定义映射

通过 frameMapper 函数自定义滚动像素到帧索引的映射关系，完全控制动画节奏。

🎨 TypeScript 支持

完整的 TypeScript 类型定义，提供优秀的开发体验和代码智能提示。

🔧 灵活配置

支持水平/垂直滚动、事件系统、错误处理等丰富的配置选项，满足各种使用场景。

💫 加载动画

内置精美的加载动画，在图片预处理期间为用户提供视觉反馈，提升用户体验。

📈 智能分层加载

独创的 large 参数优化策略，采用分层递进式加载，优先加载关键帧实现快速预览，后台继续加载完整细节帧，大幅提升大型动画的启动速度。

快速开始 

import ScrollFrameCanvas from '@byte.n/scroll-frame-canvas';

const player = new ScrollFrameCanvas({
  total: 100,
  imageFactory: async (i) => `./frames/frame-${i}.jpg`,
  canvasEle: document.getElementById('canvas'),
  scrollbarEle: window,
  scrollAxis: 'y',
  frameMapper: (scrollPixels) => Math.round(scrollPixels / 10),
  onInitComplete: () => console.log('Ready!')
});

player.init().then(() => player.play());

📋 ScrollFrameCanvas 初始化参数说明

基础配置

canvasEle: HTMLCanvasElement - Canvas 元素（必填）
scrollbarEle: HTMLElement | Window | Document - 滚动容器（必填）
scrollAxis: 'x' | 'y' - 滚动轴方向（必填）
frameMapper: Function - 滚动像素到帧索引的映射函数（必填）

数据源配置

images: Array<HTMLImageElement | ImageBitmap | string> - 图片数组
total: number - 总帧数
imageFactory: Function - 异步图片工厂函数
maxConcurrentLoads: number - 最大并发加载数（默认: 6）

渲染配置

scaleMode: 'contain' | 'cover' | 'fill' - 缩放模式（默认: 'contain'）
resetScrollOnInit: boolean - 初始化时重置滚动位置（默认: true）
exitAnimationFrameRate: number - 退出动画帧率（默认: 75）

性能优化

large.enabled: boolean - 启用分层加载（默认: true）
large.factor: number - 分层因子，必须是2的幂次方（默认: 4）
large.showBackgroundProgress: boolean - 显示后台加载进度（默认: true）

事件回调

onFrame: (frame: number, offset: number) => void - 帧更新回调
onComplete: () => void - 动画完成回调
onInitComplete: () => void - 初始化完成回调
onError: (error: Error) => void - 错误回调

自定义渲染

customMainLoading: Function - 自定义主加载动画
customBackgroundLoading: Function - 自定义后台加载动画

🔧 ScrollFrameCanvas 事件、实例函数说明

生命周期方法

init(): Promise<this> - 初始化并预加载所有帧
destroy(): void - 销毁实例并清理资源

播放控制

play(): void - 开始播放动画
pause(): void - 暂停播放
stop(): void - 停止并重置到第0帧

帧控制

setFrame(frameIndex: number): void - 设置当前帧
getCurrentFrame(): number - 获取当前帧索引
getTotalFrames(): number - 获取总帧数

事件系统

on('frame', callback): 监听帧更新事件
on('complete', callback): 监听动画完成事件
on('initComplete', callback): 监听初始化完成事件
on('error', callback): 监听错误事件

适用场景

产品展示 故事叙述 交互动画 数据可视化 创意展示