使用 GSAP 实现无障碍动画指南
介绍如何用matchMedia和prefers-reduced-motion构建无障碍GSAP动画,简化ScrollTrigger效果、添加暂停控件,并测试动态效果偏好。
在 GSAP 中处理 prefers-reduced-motion 的标准做法,是向 gsap.matchMedia() 传入一个条件对象(conditions object)。GSAP 会针对当前匹配的动效偏好运行你的 setup 函数;当用户更改该设置时,GSAP 会撤销(revert)该函数创建的所有内容,然后重新运行它。
团队通常是在无障碍审计标记出某个滚动固定(scroll-pinned)的首屏 hero 区块或循环播放的跑马灯(marquee)之后才着手处理这一问题的,而设计师并不希望为了修复问题就把页面变成一份静态 PDF。
检查媒体查询只是工作的一部分。一套无障碍的 GSAP 方案还需要更克制的 ScrollTrigger、暂停控件、在脚本未运行时依然可见的内容,以及一套用于测试上述所有内容的方法。如果你需要了解该媒体查询本身的背景知识,可以阅读 OpenReplay 的 prefers-reduced-motion 指南。gsap.matchMedia() 要求 GSAP 3.11.0 或更高版本。
核心要点
- 当查询不再匹配时,
gsap.matchMedia()会撤销 setup 函数中创建的所有动画和 ScrollTrigger,因此操作系统“减少动态效果”设置的更改无需重新加载页面即可生效。 - 在减弱动效模式下,将大幅度的位移、旋转和缩放替换为简短的透明度淡入,确保内容依然会出现。
- 减弱动效的 ScrollTrigger 分支应去掉
pin和scrub,只需在每个元素进入视口时将其淡入即可。 - WCAG 2.2.2 暂停、停止、隐藏(Pause, Stop, Hide,A 级)要求为自动播放的动效提供暂停、停止或隐藏控件。仅检查 prefers-reduced-motion 本身并不能满足该要求。
- 让动画内容在其默认 CSS 状态下保持可读,这样即使没有任何动画运行,也不会有内容停留在
opacity: 0。
使用 gsap.matchMedia() 根据 prefers-reduced-motion 为 GSAP 动画设置分支
gsap.matchMedia() 只在查询匹配时运行 setup 函数。当查询不再匹配时,它会撤销该函数创建的所有动画和 ScrollTrigger。你可以传入一个条件对象作为查询,处理函数随后即可从 context.conditions 中以布尔值的形式读取每个条件。
const mm = gsap.matchMedia();
const conditions = {
isMotion: "(prefers-reduced-motion: no-preference)",
isReduced: "(prefers-reduced-motion: reduce)",
};
mm.add(conditions, (context) => {
const { isMotion, isReduced } = context.conditions;
if (isMotion) {
gsap.from(".hero-card", { opacity: 0, x: -200, rotation: -8, duration: 1 });
}
if (isReduced) {
gsap.from(".hero-card", { opacity: 0, duration: 0.4 });
}
});
目标是减弱动效,而不是彻底移除动效。在减弱动效分支中,大幅度的水平位移和旋转被替换为简短的淡入。卡片依然会出现,也依然能吸引注意力,只是不会有任何东西在屏幕上横向移动。GSAP 的无障碍动画指南提供了一套判断标准,用于决定何时简化动画、何时完全去掉动画。matchMedia() 内部已经封装了 gsap.context(),因此不要再在外面包裹一层 context。
为减弱动效模式调整 ScrollTrigger
减弱动效的 ScrollTrigger 分支应去掉 pin 和 scrub,并在每个元素进入视口时将其淡入。固定(pin)会接管用户的滚动操作,而 scrub 会将动画与每一次滚动手势绑定。这两者正是减弱动效分支需要避免的。
mm.add(conditions, (context) => {
if (context.conditions.isMotion) {
const tl = gsap.timeline({
scrollTrigger: { trigger: ".story", pin: true, scrub: 1, end: "+=200%" },
});
tl.from(".story-step", { opacity: 0, y: 100, stagger: 0.5 });
} else {
gsap.utils.toArray(".story-step").forEach((step) => {
gsap.from(step, { opacity: 0, duration: 0.4, scrollTrigger: { trigger: step } });
});
}
});
在最简单的用法中,ScrollTrigger 会在触发元素进入视口时播放一次动画,这正适合淡入效果。你无需手动 kill 任何实例:如果偏好设置发生变化,matchMedia 会撤销带固定效果的时间轴,并构建淡入版本。关于完整动效一侧的固定与 scrub 用法,请参阅 OpenReplay 的 ScrollTrigger 实战教程。会话回放(session replay)可以显示用户快速滚过固定区块或在动画中途停下的情况,从而揭示动效在哪些地方妨碍了用户。
暂停控件与页内动效开关
WCAG 2.2.2 暂停、停止、隐藏是一项 A 级成功标准,它要求:对于自动开始、持续超过五秒并与其他内容同时呈现的动态内容,必须提供暂停、停止或隐藏的方式。仅遵循 prefers-reduced-motion 并不能满足 WCAG 2.2.2,因为从未修改过操作系统设置的用户仍然会看到完整的动画。W3C 关于 2.2.2 的 Understanding 文档还建议:如果页面中包含多个移动、闪烁、滚动或自动更新的元素,应提供单一机制来统一控制所有这些元素。
| 成功标准 | 级别 | GSAP 实现方式 |
|---|---|---|
| 2.2.2 暂停、停止、隐藏(Pause, Stop, Hide) | A | 调用 timeline.pause() / timeline.play() 的暂停按钮 |
| 2.3.3 交互触发的动画(Animation from Interactions) | AAA | gsap.matchMedia() 减弱动效分支 |
WCAG 2.2.2 和 2.3.3 针对的是不同类型的动效。2.3.3 适用于由用户交互触发的动效,而 2.2.2 适用于页面自行启动的动效。OpenReplay 的无障碍动画概述介绍了更全面的相关准则。
const toggle = document.querySelector("#reduce-motion");
const pauseBtn = document.querySelector("#pause-motion");
toggle.checked = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
toggle.addEventListener("change", gsap.matchMediaRefresh);
mm.add(conditions, (context) => {
const reduce = context.conditions.isReduced || toggle.checked;
pauseBtn.hidden = reduce;
if (reduce) return; // marquee stays static
const tl = gsap.timeline({ repeat: -1 });
tl.to(".marquee-track", { xPercent: -50, duration: 20, ease: "none" });
pauseBtn.textContent = "Pause animation";
const onClick = () => {
tl.paused() ? tl.play() : tl.pause();
pauseBtn.textContent = tl.paused() ? "Play animation" : "Pause animation";
};
pauseBtn.addEventListener("click", onClick);
return () => pauseBtn.removeEventListener("click", onClick);
});
pause() 会暂停实例,并可选择跳转到指定时间点。不传参数时,它会停在播放头当前所在的位置。play() 会从该位置恢复播放,并确保实例既未暂停也未反向播放。paused() 不传参数时作为 getter 使用,因此可以用它来实现切换。
gsap.matchMediaRefresh() 会撤销所有处于活动状态的 matchMedia 设置,并重新运行仍然匹配的设置,因此勾选框可以立即重建所有动画。reduce = isReduced || toggle.checked 所体现的规则是:页内开关可以增加减弱效果,但绝不能覆盖操作系统发出的减弱动效请求。清理函数只负责移除事件监听器。不要在其中调用 context.revert(),因为 matchMedia 会自行处理撤销操作。
确保动画未运行时内容依然可见
动画内容在其默认 CSS 状态下应完全可读。这样,即使脚本执行失败或没有任何 matchMedia 分支运行,也不会有内容停留在 opacity: 0 或 visibility: hidden 状态。这种情况在实践中确实会发生:基于条件对象构建的 gsap.matchMedia() 处理函数,在所有条件都不匹配时根本不会运行。
/* Avoid: content is invisible until JavaScript reveals it */
.reveal { opacity: 0; }
// Prefer: CSS leaves .reveal visible; GSAP animates from hidden to that state
mm.add(conditions, () => {
gsap.from(".reveal", { opacity: 0, duration: 0.4 });
});
gsap.from() 会从你传入的值过渡到元素的当前状态。这意味着静止状态始终可见,只有动画才会隐藏该元素。autoAlpha(GSAP 中将 opacity 与 visibility 合二为一的属性)同样如此:应让内容从 autoAlpha: 0 开始动画,而不是在 CSS 中用 opacity: 0 和 visibility: hidden 将其隐藏,再等待补间动画(tween)把它显示出来。
元素移动时的焦点顺序
x、y 和 scale 等 GSAP 变换只在视觉上移动元素,并不会改变其在 DOM 中的位置。因此,键盘焦点和屏幕阅读器的朗读顺序遵循的是标记结构,而非动画效果。请保持 DOM 的阅读顺序合乎逻辑,不要通过对布局属性做动画来伪造另一种顺序。
不要在元素获得焦点时移动它,也不要在交互元素尚未就位前就让它可点击。一个从光标下滑走的按钮,就是一个会“逃跑”的目标。对于文字动画,SplitText 默认就会处理屏幕阅读器的兼容问题。在 aria: "auto" 模式下,它会为被拆分的元素添加一个由其文本填充的 aria-label,并为其内部的行、单词和字符元素添加 aria-hidden。这样,无障碍树暴露的是一个完整可读的字符串,而不是零散的片段。这一默认行为适用于标题元素,但 ARIA 禁止在通用元素(如普通的 <div>、<span> 或 <p>)上使用 aria-label,无障碍检查工具会将其标记为问题。对于这类元素,或当拆分文本中包含必须被朗读的嵌套链接时,请使用 aria: "none"(不添加任何 ARIA 属性),并另外提供一份仅供屏幕阅读器读取的文本副本。
如何在 GSAP 中测试减弱动效?
在页面打开的状态下切换减弱动效偏好设置,即可测试 GSAP 的两个动效分支。由于 gsap.matchMedia() 会响应设置变化,你应该能看到动画在不重新加载页面的情况下完成切换。你可以开启操作系统的“减少动态效果”设置(各平台的设置位置请参阅 MDN 的 prefers-reduced-motion 用户偏好设置),也可以在 Chrome 中进行模拟。在 Chrome DevTools 中打开 Rendering 面板,找到 “Emulate CSS media feature prefers-reduced-motion”,然后选择 prefers-reduced-motion: reduce。
请检查以下几项:
- 固定区块不再被固定。
- 循环动效要么已消失,要么有一个可通过键盘访问且能正常工作的暂停按钮。
- 禁用 JavaScript 后,所有内容依然可见。
- 页内开关能够立即重建动画。
结论
一套无障碍的 GSAP 方案既保留了设计效果,又把控制权交给了用户。matchMedia 将大幅度的运动替换为淡入效果,并与操作系统设置保持同步;ScrollTrigger 在减弱动效分支中不再固定元素;一个真正的按钮可以暂停任何长时间运行的动画;即使没有 JavaScript,内容也依然可见。请从审计中标记出的固定或循环动画入手,为其编写减弱动效分支和暂停控件,并使用 DevTools 模拟对两种模式进行测试,然后再处理下一个动画。
常见问题
如何在 React 中使用 gsap.matchMedia() 处理减弱动效?
在 effect 内部创建 matchMedia 实例,并返回一个调用 mm.revert() 的清理函数。撤销该实例会同时撤销其处理函数创建的所有动画和 ScrollTrigger,因此无需再单独使用 gsap.context()。清理函数在开发环境中尤为重要,因为 React 严格模式(Strict Mode)会对组件执行挂载、卸载、再挂载的流程,否则同一个动画可能会被启动两次。
CSS 中针对 prefers-reduced-motion 的重置规则能停止 GSAP 动画吗?
不能。在 prefers-reduced-motion: reduce 块中缩短 animation 和 transition 时长的全局 CSS 规则,只会影响 CSS 动画和过渡。GSAP 通过 JavaScript 在每一帧写入内联样式值来实现动画,因此其补间动画和 ScrollTrigger 会继续运行。请使用 gsap.matchMedia() 的减弱动效分支来处理 GSAP 动效,CSS 重置规则则保留用于 CSS 驱动的动效。
当用户更改减弱动效设置时,正在运行的 GSAP 动画会发生什么?
gsap.matchMedia() 会撤销该动画,并针对新的偏好设置重新运行处理函数。撤销操作会移除动画添加的内联样式,并撤销处理函数中创建的 ScrollTrigger(包括其固定效果)。随后,新匹配的分支会从头构建其动画,因此执行到一半的完整动效补间动画不会继续播放。减弱动效版本会从元素的默认 CSS 状态开始。
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.
Star on GitHub12k