从补间到叙事：GSAP 动画实战 · 公开阅读

附录A：API速查手册

按功能检索 GSAP 核心方法、配置项与插件 API。

本章小节

本章按功能分类列出GSAP核心API，每个API一行说明+参数签名，便于快速查阅。

A.1 gsap 核心方法

动画创建

API	签名与说明
`gsap.to(target, vars)`	从当前值过渡到目标值
`gsap.from(target, vars)`	从指定值过渡到当前值（入场动画）
`gsap.fromTo(target, fromVars, toVars)`	从指定起始值过渡到指定结束值
`gsap.set(target, vars)`	立即设置属性值，不产生动画

Timeline

API	签名与说明
`gsap.timeline(vars)`	创建时间线实例，`vars`包含{repeat, yoyo, defaults, onComplete}等
`tl.to(target, vars, position)`	在时间线上添加过渡动画
`tl.from(target, vars, position)`	在时间线上添加入场动画
`tl.fromTo(target, fromVars, toVars, position)`	在时间线上添加指定起止点的动画
`tl.set(target, vars, position)`	在时间线指定位置设置属性值
`tl.add(child, position)`	添加子动画或子时间线
`tl.addLabel(name, position)`	在时间线指定位置添加标签
`tl.addPause(position, callback)`	在指定位置暂停
`tl.call(callback, params, position)`	在指定时刻执行回调函数
`tl.play(from, suppressEvents)`	开始播放（可指定起始位置）
`tl.pause(atTime, suppressEvents)`	暂停（可指定暂停时间点）
`tl.resume()`	从暂停位置继续播放
`tl.restart(includeDelay, suppressEvents)`	重新开始（可指定是否包含delay）
`tl.reverse(from, suppressEvents)`	反向播放
`tl.seek(position, suppressEvents)`	跳转到指定时间点
`tl.timeScale(value)`	设置/获取播放速度（0.5=半速, 2=两倍速）
`tl.progress(value, suppressEvents)`	获取/设置播放进度（0-1）
`tl.duration(value)`	获取/设置单轮时长（不含 repeat/repeatDelay）
`tl.totalDuration(value)`	获取/设置总时长（含重复播放）
`tl.totalProgress(value)`	获取/设置总进度（含重复播放）
`tl.kill()`	停止并从父时间线移除，当前样式保留
`tl.clear()`	清空所有子动画，时间线保留
`tl.invalidate()`	清除记录的起始值，下次播放时重新读取
`tl.isActive()`	检查动画是否处于活动状态
`tl.recent()`	返回最近添加的子动画
`tl.tweenTo(position, vars)`	从当前位置创建过渡到指定位置的动画
`tl.tweenFromTo(from, to, vars)`	从A时间点创建过渡到B时间点的动画
`tl.getChildren(nested, tweens, timelines)`	获取所有子动画
`tl.shiftChildren(amount, adjustLabels)`	偏移所有子动画的时间戳

全局控制

API	签名与说明
`gsap.registerPlugin(...plugins)`	注册插件（ScrollTrigger, Flip, Observer等）
`gsap.globalTimeline`	全局时间线，未加入自定义时间线的动画默认挂载于此
`gsap.ticker`	动画引擎的帧循环控制器
`gsap.ticker.fps(value)`	设置目标帧率
`gsap.ticker.add(callback)`	添加每帧回调
`gsap.ticker.remove(callback)`	移除每帧回调
`gsap.ticker.lagSmoothing(threshold, lag)`	调整延迟平滑参数
`gsap.defaults(vars)`	设置全局默认动画参数
`gsap.config(settings)`	全局配置（autoSleep, force3D, nullTargetWarn等）
`gsap.killTweensOf(target, props)`	终止指定元素的所有或部分动画
`gsap.getProperty(target, property, unit)`	读取元素的动画属性值
`gsap.quickTo(target, property, vars)`	创建高性能更新函数，复用tween实例
`gsap.quickSetter(target, property, unit)`	创建无动画的高性能setter函数
`gsap.getById(id)`	通过ID查找动画实例
`gsap.isTweening(target)`	检查目标元素是否正在执行动画
`gsap.exportRoot(vars, omitTimeline)`	导出所有动画到新时间线
`gsap.context(callback, scope)`	创建动画作用域，统一管理动画生命周期
`gsap.matchMedia()`	响应式断点媒体查询，不同屏幕不同动画
`gsap.matchMediaRefresh()`	刷新所有matchMedia条件
`gsap.effects`	注册自定义effect的命名空间

A.2 Tween属性（vars参数）

动画目标属性

属性	类型	说明
`x`, `y`, `z`	Number/String	位移（单位：px/%/vw）
`xPercent`, `yPercent`	Number	相对于自身尺寸的百分比位移
`rotation`, `rotationX`, `rotationY`, `rotationZ`	Number	旋转角度（度）
`scale`, `scaleX`, `scaleY`	Number	缩放倍数（1=原始大小）
`skewX`, `skewY`	Number	倾斜
`transformOrigin`	String	变换的原点（"50% 50%"=中心）
`opacity`	Number	透明度（0=全透明, 1=不透明）
`autoAlpha`	Number	opacity+visibility组合（到0时自动visibility:hidden）
`width`, `height`	Number/String	尺寸
`backgroundColor`	String/Number	背景色
`color`	String/Number	文字颜色
`borderColor`	String/Number	边框颜色
`boxShadow`	String	阴影
`progress`	Number	驱动 Animation 的 progress 属性时使用

时间与播放控制

属性	类型	默认值	说明
`duration`	Number	0.5	动画时长（秒）
`delay`	Number	0	等多久再开始（秒）
`repeat`	Number	0	重复次数（-1=无限循环）
`repeatDelay`	Number	0	每次重复之间的停顿（秒）
`repeatRefresh`	Boolean	false	每次重复时重新读取起始值（动态适应）
`yoyo`	Boolean	false	正放一遍再倒放一遍
`yoyoEase`	Boolean/Ease	false	yoyo时是否把缓动也反过来
`ease`	String/Function	"power1.out"	缓动节奏
`stagger`	Number/Object	0	多个元素时逐个错开启动
`paused`	Boolean	false	创建后先停着，不自动播放
`overwrite`	Boolean/"auto"	false	是否终止同目标上的旧动画或活动动画的冲突属性
`immediateRender`	Boolean	true	是否立即渲染第一帧（from类动画）
`lazy`	Boolean	true	是否延迟写入直到tick（减少重排）
`force3D`	Boolean/String	"auto"	强制3D加速渲染

回调函数

回调	触发时机	参数
`onStart`	动画开始时	默认无参数，使用对应 Params 显式传参
`onUpdate`	每帧更新时	默认无参数，使用对应 Params 显式传参
`onRepeat`	每次重复时	默认无参数，使用对应 Params 显式传参
`onComplete`	动画完成时	默认无参数，使用对应 Params 显式传参
`onReverseComplete`	反向播放完成时	默认无参数，使用对应 Params 显式传参
`onInterrupt`	动画被中断时	默认无参数，使用对应 Params 显式传参
`callbackScope`	回调函数中的this指向	Object

stagger 对象参数

stagger: {
  each: 0.1,          // 每个元素之间间隔多久
  from: "center",     // 从哪开始："start"/"center"/"end"/"edges"/"random"/index
  grid: [3, 4],       // 网格布局 [列, 行]
  axis: "y",          // 网格轴向：null/"x"/"y"
  ease: "power2.in",  // 延迟的时间分布节奏
  amount: 2,          // 总散布时间（替代each，自动均分）
  repeat: 1,          // 初始元素重复次数
  yoyo: true,         // 初始yoyo
}

A.3 ScrollTrigger 属性

构造参数

ScrollTrigger.create({
  // 触发元素
  trigger: ".element",        // 触发元素选择器
  start: "top center",        // 触发起点
  end: "bottom top",          // 触发终点
  // 固定值：start/end也支持 "top+=100" 或 "20px" 或 0.5(百分比)

  // 动画
  animation: myTimeline,      // 关联的动画
  toggleActions: "play none none none", // onEnter/onLeave/onEnterBack/onLeaveBack

  // 固定模式
  pin: true,                  // 固定触发器元素
  pinSpacing: true,           // 固定后是否保留空间
  pinReparent: false,         // 是否移动pin元素到body
  pinType: "fixed",           // "fixed" | "transform"

  // 控制
  scrub: true,                // 动画与滚动同步（true=跟随滚动, Number=平滑延迟秒数）
  snap: 0.2,                  // 吸附（Number=进度量, Array=吸附点, Function）
  fastScrollEnd: true,        // 快速滚动结束时自动定位到吸附点
  anticipatePin: 0,           // 预测固定（0-1）

  // 回调
  onEnter: (self) => {},
  onLeave: (self) => {},
  onEnterBack: (self) => {},
  onLeaveBack: (self) => {},
  onUpdate: (self) => {},
  onToggle: (self) => {},
  onRefresh: (self) => {},
  onSnapComplete: (self) => {},
  onScrubComplete: (self) => {},

  // 工具方法
  invalidateOnRefresh: false, // refresh时是否清除记录的起始值
  id: "myTrigger",            // 唯一ID
  markers: false,             // 开发标记
  once: false,                // 只触发一次
  toggleClass: "active",      // 切换的class

  // 容器滚动（非window滚动）
  scroller: document.body,    // 滚动容器

  // 水平滚动
  horizontal: false,          // 是否水平方向

  // 其他
  preventOverlaps: false,     // 防止多个ScrollTrigger动画重叠
  refreshPriority: 0,         // refresh优先级（越大越先执行）
  endTrigger: null,           // end位置的参考元素（不同于trigger）
  containerAnimation: null,   // 容器动画（水平滚动场景）
})

ScrollTrigger 静态方法

方法	说明
`ScrollTrigger.create(config)`	创建ScrollTrigger实例
`ScrollTrigger.getAll()`	获取所有实例
`ScrollTrigger.getById(id)`	按ID查找实例
`ScrollTrigger.refresh(safe)`	重新计算所有trigger位置
`ScrollTrigger.update()`	刷新所有trigger状态
`instance.kill()`	停止并销毁指定 ScrollTrigger 实例
`ScrollTrigger.killAll()`	销毁全部实例
`ScrollTrigger.sort(fn)`	排序所有实例
`ScrollTrigger.saveStyles(targets)`	保存元素内联样式
`ScrollTrigger.revert()`	恢复之前保存的样式
`ScrollTrigger.matchMedia(config)`	响应式ScrollTrigger
`ScrollTrigger.clearMatchMedia(media)`	清除matchMedia
`ScrollTrigger.isScrolling()`	检查是否正在滚动
`ScrollTrigger.addEventListener(type, callback)`	监听refresh/scrollEnd事件
`ScrollTrigger.removeEventListener(type, callback)`	移除监听
`ScrollTrigger.batch(targets, config)`	批量创建trigger
`ScrollTrigger.maxScroll(scroller)`	获取最大滚动值
`ScrollTrigger.positionInViewport(el, referencePoint)`	计算元素在视口中的位置
`ScrollTrigger.defaults(config)`	设置全局默认值
`ScrollTrigger.observe(config)`	创建 Observer，统一处理滚轮、触摸与指针输入
`ScrollTrigger.normalizeScroll(enable)`	统一不同设备滚动行为

实例属性（self对象）

属性	说明
`self.trigger`	触发器元素
`self.start`	起始计算值
`self.end`	结束计算值
`self.progress`	进度（0-1）
`self.direction`	滚动方向（1=向下, -1=向上）
`self.isActive`	是否处于触发范围
`self.animation`	关联的动画
`self.vars`	创建时的配置
`self.scroller`	滚动容器
`self.getVelocity()`	滚动速度（px/s）
`self.refresh()`	刷新此实例
`self.kill()`	销毁此实例

A.4 Utility 工具方法

方法	签名与说明
`gsap.utils.checkPrefix(property)`	获取属性的浏览器前缀
`gsap.utils.clamp(min, max, value)`	将值限定在[min, max]范围内
`gsap.utils.distribute(config)`	创建分布函数，用于stagger中定制分布方式
`gsap.utils.getUnit(value)`	获取CSS值的单位，如"100px" → "px"
`gsap.utils.interpolate(from, to, progress)`	在from和to之间按比例线性插值
`gsap.utils.mapRange(inMin, inMax, outMin, outMax, value)`	将值从输入范围映射到输出范围
`gsap.utils.normalize(min, max, value)`	将值标准化到0-1区间
`gsap.utils.pipe(...functions)`	管道函数，前一个函数的输出作为下一个的输入
`gsap.utils.random(min, max, snapIncrement, returnFunction)`	生成随机数，可指定步长
`gsap.utils.selector(scope)`	创建限定作用域的选择器函数
`gsap.utils.shuffle(array)`	随机打乱数组
`gsap.utils.snap(snapIncrement, value)`	将值吸附到最近的步长值
`gsap.utils.splitColor(color)`	将颜色字符串拆分为rgba四个分量
`gsap.utils.toArray(value, leaveStrings)`	将选择器、NodeList等转换为数组
`gsap.utils.unitize(func, unit)`	给函数返回值添加单位
`gsap.utils.wrap(start, end, value)`	超范围后循环回另一端
`gsap.utils.wrapYoyo(start, end, value)`	超范围后往复回绕
`gsap.parseEase(name, vars)`	解析缓动字符串

A.5 缓动函数速查

内置缓动类型

类别	可用函数	特点
`none`	—	匀速，无缓动
`power1`~`power4`	`.in` `.out` `.inOut`	基础缓动，数字越大效果越强
`sine`	`.in` `.out` `.inOut`	正弦缓动，柔和自然
`expo`	`.in` `.out` `.inOut`	指数级缓动，加减速明显
`circ`	`.in` `.out` `.inOut`	圆形曲线
`back`	`.in(overshoot)` `.out(overshoot)` `.inOut(overshoot)`	超出目标再回拉，默认越界量1.7
`elastic`	`.in(amp,freq)` `.out(amp,freq)` `.inOut(amp,freq)`	弹性缓动，类似橡皮筋回弹
`bounce`	`.in` `.out` `.inOut`	弹跳缓动
`steps(n)`	—	逐帧跳变，n帧完成
`rough(config)`	—	毛刺抖动效果
`slow(normal, stretch)`	—	慢速缓动
`expoScale(start, end)`	—	指数缩放

使用示例："power2.inOut" "back.out(2)" "elastic.out(1,0.3)" "steps(12)" "rough({template: none.out, strength: 1})"

速查表要点	速记
创建动画	`to`/`from`/`fromTo`/`set`
时间线	`timeline()` → `.to()` `.add()` `.seek()` `.kill()`
ScrollTrigger	`trigger`/`start`/`end`/`scrub`/`pin`
工具函数	`clamp`/`mapRange`/`interpolate`/`random`/`snap`/`toArray`
缓动三件套	`.in`（加速）/`.out`（减速）/`.inOut`（中间快两头慢）

插件前提：RoughEase、SlowMo、ExpoScaleEase 来自 gsap/EasePack，先导入并 gsap.registerPlugin(RoughEase, SlowMo, ExpoScaleEase)。CustomEase 也需单独注册。

A.6 按问题查演示

想核实什么	对应章节
时间进度和属性进度	第2章：核心概念
immediateRender、repeat、overwrite	第3章：三大 API
标签和位置参数	第4章：Timeline
pin 与四方向事件	第5章：ScrollTrigger
seek、reverse 与 resume	第7章：控制方法
wrap、clamp、snap 边界	第9章：Utility
组件作用域与还原	第14章：框架集成
路径、文字与惯性	第18章：高级插件

回调默认不会自动收到 Tween 参数。可用 onCompleteParams 等显式传参，或普通函数中的 this 获取动画；箭头函数的 this 不由 callbackScope 改写。速查表用于确认签名，使用前仍需准备 DOM、注册对应插件和清理资源。