animator-clip

一个基于 JavaScript 的 requestAnimationFrame API 封装的轻量级 JS 动画插件。

特性

• 高性能：跟随系统绘制频率执行动画，性能优于传统 setTimeout 动画，甚至优于 CSS 动画
• CPU 节能：页面未激活时自动暂停渲染，恢复后从断点继续，有效节省 CPU 开销
• 兼容性好：不支持 requestAnimationFrame 的浏览器自动降级为 setTimeout 模拟
• 链式调用：支持 chain() 串联多个动画帧，实现顺序动画
• 自由模式：支持 transform 等复合属性动画，完全自定义更新逻辑
• TypeScript：完整的类型定义支持

安装

# npm
npm install animator-clip

# 安装指定版本
npm install [email protected]

# yarn
yarn add animator-clip

# 安装指定版本
yarn add [email protected]

# pnpm
pnpm add animator-clip

# 安装指定版本
pnpm add [email protected]

CDN 使用

<!-- 引入固定版本 -->
<script src="https://unpkg.com/[email protected]/lib/animator-clip.umd.js"></script>
<!-- 始终引入最新版本 -->
<script src="https://unpkg.com/animator-clip/lib/animator-clip.umd.js"></script>

CDN 引入后通过 window.AnimatorClip 获取：

const { Animator, Clip } = window.AnimatorClip

快速上手

import { Animator, Clip } from 'animator-clip'

// 创建动画实例，绑定 DOM 元素
const animator = new Animator(el, {
  onComplete(clip, el) {
    console.log('动画完成')
  }
})

// 创建单一动画帧实例
const clip = new Clip({
  style: 'opacity',  // 动画属性
  value: 0,          // 目标值
  speed: -0.01       // 每帧变化量（负数表示减小）
})

// 将 clip 添加到 animator 并开始动画
animator.addClip(clip).start()

核心 API

Animator

动画实例，与 DOM 元素绑定，管理多个 Clip。

const animator = new Animator(el, options)

| 参数 | 类型 | 说明 | | --- | --- | --- | | el | HTMLElement \| string | 绑定的 DOM 元素或选择器 | | options.onStart | (clip, el) => void | 动画开始事件 | | options.onStop | (clip, el) => void | 动画停止事件 | | options.onReset | (clip, el) => void | 动画重置事件 | | options.onBeforeUpdate | (clip, el, style?, value?) => void | 动画帧更新前事件 | | options.onUpdate | (clip, el, style?, value?) => void | 动画帧更新时事件 | | options.onComplete | (clip, el) => void | 动画完成事件 |

主要方法：

| 方法 | 说明 | | --- | --- | | addClip(clip) | 将 clip 添加到队列 | | removeClip(clip) | 将 clip 移出队列 | | removeAllClips() | 移除所有 clip | | getClips() | 获取正在运行的 clip | | getStopClips() | 获取已停止的 clip | | getCompleteClips() | 获取已完成的 clip | | start() | 开始动画 | | stop() | 停止动画 | | reset(resetStyle?) | 重置动画，resetStyle 默认 true |

Clip

单一动画帧，定义具体的动画效果。

const clip = new Clip(options)

| 参数 | 类型 | 说明 | | --- | --- | --- | | options.style | keyof CSS.Properties | 动画属性名，如 opacity、fontSize | | options.value | string \| number | 样式目标值，支持 px、rem、em 单位 | | options.speed | number | 每帧变化量，负数表示减小 | | options.free | boolean | 是否自由模式，默认 false | | options.onStart | (el) => void | 动画开始事件 | | options.onStop | (el) => void | 动画停止事件 | | options.onReset | (el) => void | 动画重置事件 | | options.onBeforeUpdate | (el, style?, value?) => void | 帧更新前事件 | | options.onUpdate | (el, style?, value?) => void | 帧更新时事件 | | options.onComplete | (el) => void | 动画完成事件 |

主要方法：

| 方法 | 说明 | | --- | --- | | start() | 开始该 clip 动画 | | stop() | 停止该 clip 动画 | | reset(resetStyle?) | 重置该 clip 动画 | | chain(clip) | 链式调用，当前动画完成后自动执行下一个 | | emitComplete() | 主动触发完成事件（仅自由模式有效） |

主要属性：

| 属性 | 类型 | 说明 | | --- | --- | --- | | state | 0 \| 1 \| 2 \| 3 | 动画状态：0初始 / 1进行 / 2停止 / 3完成 | | interval | number | 相邻两帧的时间间隔（ms），仅更新事件中有效 | | speed | number | 动画速度，可动态修改 |

文档

完整文档请访问：https://www.so-better.cn/docs/animator-clip/

License

MIT